Lunacy MCP Server – Design Context and Handoff
Lunacy's built-in MCP server gives AI assistants local, real-time access to selected design objects and design-system context. Use it for design analysis, design-to-code workflows, documentation, asset review, brand checks, and developer handoff.
Overview
Lunacy includes a built-in local MCP server that connects compatible AI assistants to the current Lunacy project. Once enabled from Lunacy's AI menu, the server runs on the user's machine and gives the assistant structured access to live design context without requiring manual copying, screenshots, or exports for every task.
What the MCP server enables
Lunacy documents MCP access to core design information, including:
- Information about the objects currently selected in a design.
- Color variables from the active design system.
- Components and their properties.
- Images and other design assets.
- Real-time project context for design analysis and recommendations.
- Design-to-code workflows that use component hierarchy, variables, and layout details.
- Design-system documentation and developer handoff generation.
- Brand-consistency, accessibility, and design-review assistance.
- Asset-analysis workflows when combined with file-system or image-processing tools.
The MCP integration is primarily context-oriented. It helps an AI assistant understand and analyze the active Lunacy document, while broader automation and modification workflows can use Lunacy's local HTTP Automation API and plugins.
When to use it
Use Lunacy MCP when an AI workflow needs accurate, current context from a design file. Typical uses include generating React or TypeScript implementations from selected layouts, documenting components and design tokens, reviewing color and spacing consistency, preparing technical handoff notes, checking brand compliance, and comparing Lunacy designs with existing applications or documentation.
It is especially useful for teams that want design data to remain local while still giving an AI assistant enough context to produce code, reports, implementation guidance, or review feedback.
Connection and authentication
The MCP server is built into Lunacy and starts locally when the user selects AI → Model Context Protocol → MCP Server Enabled. Lunacy provides menu actions to copy either a complete MCP servers configuration file or a single server entry for an existing client configuration.
The local service uses http://localhost:31415. No API key, OAuth flow, or bearer token is documented for local access. Lunacy must remain open, and the MCP server setting must stay enabled while the client is connected.
Key considerations
The server is local and unauthenticated, so it should remain bound to localhost and should not be exposed to untrusted networks. Access reflects the active Lunacy session and selected design objects. If the client cannot connect, verify that Lunacy is running, MCP is enabled, and port 31415 is available. Users should review AI-generated code, design recommendations, and handoff documentation before using them in production.
Supported Transports
streamable_http
URL: http://localhost:31415
Frequently Asked Questions
- When should an AI assistant use the Lunacy MCP server?
- Use it when a workflow needs live context from a Lunacy design, such as design-to-code generation, component documentation, brand review, accessibility checks, design-system analysis, or developer handoff.
- What does the Lunacy MCP server add to an AI assistant's capabilities?
- It gives the assistant real-time access to selected objects, color variables, components, properties, images, and other design assets from the active Lunacy project instead of relying only on pasted descriptions or screenshots.
- What can an AI assistant access through Lunacy MCP?
- The documented integration exposes information about selected design objects, design-system color variables, component details, images, and other assets. This context can support code generation, reviews, documentation, handoff, and cross-tool workflows.
- How is authentication configured for the Lunacy MCP server?
- Lunacy runs the server locally and does not document an API key, OAuth flow, or bearer token for this connection. The user enables it from the AI menu, keeps Lunacy open, and connects the MCP client to the local server configuration copied by Lunacy.
- Which transport should be used for the Lunacy MCP server?
- Use the local HTTP MCP connection exposed by Lunacy at http://localhost:31415. Lunacy provides a copyable MCP configuration entry from its menu, and the reviewed documentation does not describe a hosted remote or SSE endpoint.