MasterGo Magic MCP
OfficialThe MasterGo Magic MCP server enables AI models to interact with MasterGo design files through:
Retrieve DSL Data: Extract structured design data using
mcp__getDsl, including component hierarchy, design properties, and code generation rules by providing file and layer IDs.Extract Component Documentation: Fetch documentation via
mcp__getComponentLinkusing URLs from the componentDocumentLinks array in the DSL data.Integration with AI Models: Serves as a bridge between AI and MasterGo, enabling design analysis and code generation based on the retrieved data.
Support for Local Development: Allows developers to build and customize the MCP service for debugging purposes.
Provides the runtime environment required for the MCP server to operate, with no external dependencies needed beyond Node.js.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MasterGo Magic MCP get the color palette from my latest design file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MasterGo Magic MCP
MasterGo Magic MCP is a standalone MCP (Model Context Protocol) service designed to connect MasterGo design tools with AI models. It enables AI models to directly retrieve DSL data from MasterGo design files.
Key Features
Retrieves DSL data from MasterGo design files
Runs directly with npx
No external dependencies required, only Node.js environment needed
Related MCP server: Vextra MCP Server
Tutorial
Example Prompts
Once the MCP server is connected, you can use the following prompts in your AI chat:
Extract SVG and preview in HTML:
Extract SVG and preview in HTML: https://{domain}/file/{fileId}?layer_id={layerId}Restore a design to code:
Restore design: https://{domain}/file/{fileId}?layer_id={layerId}Replace {domain}, {fileId}, and {layerId} with your actual values. You can also use short links:
Restore design: https://{domain}/goto/{shortLink}Restore a design and save as an HTML file:
Restore design, save as HTML file: https://{domain}/file/{fileId}?layer_id={layerId}You can also use short links:
Restore design, save as HTML file: https://{domain}/goto/{shortLink}Usage
Obtaining MG_MCP_TOKEN
Visit https://mastergo.com
Enter personal settings
Click the Security Settings tab
Find the personal access token
Click to generate the token
Permission Requirements
Important: If the tool is connected but returns a "no permission" error, please check the following conditions:
Account Version Requirement:
Requires Team Edition or higher MasterGo account
Personal free edition does not support MCP tool access
File Location Requirement:
Design files must be placed in Team Projects
Files in draft box cannot be accessed via MCP tools
Command Line Options
npx @mastergo/magic-mcp --token=YOUR_TOKEN [--url=API_URL] [--rule=RULE_NAME] [--proxy=PROXY_URL] [--format=FORMAT] [--header "Key: Value"] [--debug] [--no-rule] [--no-prefix]Parameters:
--token=YOUR_TOKEN(required): MasterGo API token for authentication--url=API_URL(optional): API base URL, defaults to http://localhost:3000--rule=RULE_NAME(optional): Add design rules to apply, can be used multiple times--proxy=PROXY_URL(optional): HTTP/HTTPS proxy URL (e.g.,http://127.0.0.1:7890), also supportsHTTPS_PROXY/HTTP_PROXYenvironment variables--header "Key: Value"(optional): Custom HTTP request header, can be used multiple times. Quote the value when it contains spaces. Custom headers override the defaults — includingContent-Typeand the auth token — so match the default key exactly when overriding. Also settable via theMG_EXTRA_HEADERSenvironment variable as a JSON object (e.g.MG_EXTRA_HEADERS='{"X-Custom":"val"}'); CLI headers take precedence over env.--format=FORMAT(optional): Default output format for design-data tools — one ofjson(default),yaml,tree. An explicit per-callformattool parameter overrides this. Also settable via theDEFAULT_FORMATenvironment variable.--debug(optional): Enable debug mode for detailed error information--no-rule(optional): Disable default rules--no-prefix(optional): Register tools without themcp__name prefix (e.g.getDslinstead ofmcp__getDsl). Some MCP clients (such as Grok Build) silently skip tools whose fully-qualifiedserver__toolname contains more than one__separator — since the server is already prefixed, amcp__getDsltool name becomesserver__mcp__getDsland is dropped. Enable this flag for those clients. Also settable via theMG_NO_PREFIXenvironment variable (1/true/yes).
You can also use space-separated format for parameters:
npx @mastergo/magic-mcp --token YOUR_TOKEN --url API_URL --rule RULE_NAME --proxy PROXY_URL --format FORMAT --header "Key: Value" --debugEnvironment Variables
Alternatively, you can use environment variables instead of command line arguments:
MG_MCP_TOKENorMASTERGO_API_TOKEN: MasterGo API tokenAPI_BASE_URL: API base URLRULES: JSON array of rules (e.g.,'["rule1", "rule2"]')DEFAULT_FORMAT: Default output format for design-data tools (json|yaml|tree); the--formatargument and an explicit per-callformattool parameter take precedence.MG_NO_PREFIX: Set to1/true/yesto register tools without themcp__name prefix (the--no-prefixargument takes priority).HTTPS_PROXY/https_proxy/HTTP_PROXY/http_proxy: HTTP(S) proxy URL (the--proxyargument takes priority)
Tool Output Format
The design-data tools (mcp__getDesignSections, mcp__getDsl, mcp__getDesignSvgs, mcp__getDesignTexts, mcp__extractSvg, mcp__getMeta) accept an optional format parameter that controls how the payload is serialized. It defaults to json, or to the value set via --format / DEFAULT_FORMAT (see Command Line Options).
Value | Description |
| Default. Compact JSON — useful when piping output into tools that expect JSON. Byte-identical to the prior behavior. |
| Fewer tokens than JSON for typical designs (flat layouts with repeated values benefit most). |
| Experimental compact format. Structural keys ( |
The format is chosen per tool call by the AI model. To influence it, mention the desired format in your prompt, for example:
Restore design, use tree format: https://{domain}/file/{fileId}?layer_id={layerId}Notes:
treeapplies to all six tools' responses:mcp__getDesignSections(section list and per-section DSL),mcp__getDsl,mcp__getDesignSvgs,mcp__getDesignTexts,mcp__extractSvg, andmcp__getMeta.mcp__getMetafalls back to JSON undertreebecause itsrulesfield is markdown (the tree layout would corrupt the markdown's headings/code blocks); other payloads render as tree. Truly unknown shapes also fall back to JSON — no data is ever mis-formatted.For
mcp__getDesignTexts,jsonis recommended for maximum verbatim-text fidelity — though all formats round-trip without data loss.All formats round-trip without data loss. An invalid or omitted
formatvalue falls back tojson.
Installing via Smithery Marketplace
Smithery is an MCP server marketplace that makes it easy to install and manage MCP services.
Method 1: Install via Smithery Website
Visit Smithery Marketplace
Click the "Connect" or "Install" button
Select your MCP client (e.g., Claude Desktop, Cursor, etc.)
Follow the prompts to complete installation and configuration
LINGMA Usage
Search for LINGMA in the VSCode extension marketplace and install it.
After logging in, click on [MCP tools] in the chat box.
Click on [MCP Square] at the top to enter the MCP marketplace, find the MasterGo design collaboration tool and install it.
After installation, go back to [MCP Servers], and edit our MCP service to replace it with your own MasterGo token.
Finally, switch the chat mode to agent mode in the chat interface.
cursor Usage
Cursor Mcp usage guide reference: https://docs.cursor.com/context/model-context-protocol#using-mcp-tools-in-agent
You can configure the MCP server using either command line arguments or environment variables:
Option 1: Using command line arguments
{
"mcpServers": {
"mastergo-magic-mcp": {
"command": "npx",
"args": [
"-y",
"@mastergo/magic-mcp",
"--token=<YOUR_TOKEN>",
"--url=https://mastergo.com"
],
"env": {}
}
}
}Option 2: Using environment variables
{
"mcpServers": {
"mastergo-magic-mcp": {
"command": "npx",
"args": ["-y", "@mastergo/magic-mcp"],
"env": {
"MG_MCP_TOKEN": "<YOUR_TOKEN>",
"API_BASE_URL": "https://mastergo.com"
}
}
}
}Option 3: Using SSE (Streamable HTTP)
No local installation required. The MCP server runs remotely and is accessed via SSE:
{
"mcpServers": {
"mastergo-magic-mcp": {
"type": "http",
"url": "https://mastergo.com/mcp/xf/sse",
"headers": {
"x-mg-useraccesstoken": "<YOUR_TOKEN>"
}
}
}
}cline Usage
Option 1: Using command line arguments
{
"mcpServers": {
"@master/mastergo-magic-mcp": {
"command": "npx",
"args": [
"-y",
"@mastergo/magic-mcp",
"--token=<YOUR_TOKEN>",
"--url=https://mastergo.com"
],
"env": {}
}
}
}Option 2: Using environment variables
{
"mcpServers": {
"@master/mastergo-magic-mcp": {
"command": "npx",
"args": ["-y", "@mastergo/magic-mcp"],
"env": {
"MG_MCP_TOKEN": "<YOUR_TOKEN>",
"API_BASE_URL": "https://mastergo.com"
}
}
}
}Open Code Usage
Open Code uses a mcp configuration block with type: "local" and command array:
{
"mcp": {
"mastergo-magic-mcp": {
"type": "local",
"command": [
"npx",
"-y",
"@mastergo/magic-mcp",
"--token=<YOUR_TOKEN>",
"--url=https://mastergo.com"
],
"environment": {
"NPM_CONFIG_REGISTRY": "https://registry.npmjs.org/"
},
"enabled": true
}
}
}Project Structure
src Directory
The src directory contains the core implementation of the MasterGo Magic MCP service:
index.ts: Entry point of the application that initializes the MCP server and registers all toolshttp-util.ts: Utility for handling HTTP requests to the MasterGo APItypes.d.ts: TypeScript type definitions for the project
src/tools
Contains implementations of MCP tools:
base-tool.ts: Base class for all MCP toolsget-dsl.ts: Tool for retrieving DSL (Domain Specific Language) data from MasterGo design filesget-component-link.ts: Tool for retrieving component documentation from linksget-meta.ts: Tool for retrieving metadata informationget-component-workflow.ts: Tool providing structured component development workflow for Vue and React components, generating workflow files and component specifications
src/markdown
Contains markdown files with additional documentation:
meta.md: Documentation about metadata structure and usagecomponent-workflow.md: Component development workflow documentation guiding structured component development process
Local Development
Run
yarnandyarn buildto install dependencies and build the codeFind the absolute path of
dist/index.jsAdd local MCP configuration with your token
"mastergo-mcp-local": {
"command": "node",
"args": [
"absolute/path/to/dist/index.js",
"--token=mg_xxxxxx",
"--url=https://mastergo.com",
"--debug"
],
"env": {}
},Restart your editor to ensure the local MCP is enabled
After successful execution, you can debug based on the local running results. You can build your own MCP service based on your modifications.
We welcome your code contributions and look forward to building MasterGo's MCP service together.
License
ISC
Available Tools
12 toolsmcp__C2dA
使用此工具将代码文件发送到 MasterGo MCP 服务进行 C2D(代码转设计)处理,将用户代码同步到设计稿。
参数说明:
filePath:HTML 文件的完整路径(如 /path/to/file.html),工具会自动读取文件内容并发送给后端。
fileId: 不提供 shortLink 时至少需要 fileId。layerId 不是必填,没有就不要传。
layerId: 可选。图层 ID(只读取 URL 参数 layer_id)。不传或解析不到则仅按 file 维度同步;pageid/page_id 不会被当作 layerId。
shortLink:可选,短链接形式(例如 https://{domain}/goto/xxxx)。 注意事项:只允许使用 URL 中的 layer_id 参数作为 layerId,严禁将 pageid/page_id 等任何页面 ID 当作 layerId。 如果短链接或 URL 中没有解析出 layer_id,则不传 layerId。
工具会读取 filePath 指定文件的内容,并传给后端,附带 fileId 与可选的 layerId。
Inputs: filePath (required), fileId, layerId, shortLink.
mcp__extractSvgA
Extract SVG data from MasterGo design files. This tool retrieves the DSL from a design layer, finds all PATH nodes (typically inside INSTANCE/icon components), resolves their color references, and generates SVG markup strings. You can provide either:
fileId and layerId directly, or
a short link (like https://{domain}/goto/LhGgBAK) Returns { count, svgs: [{ name, id, svg }] } — one entry per icon/instance found in the design.
Inputs: fileId, format, layerId, shortLink, +2 more.
mcp__getComponentGeneratorB
Users need to actively call this tool to get the component development workflow. When Generator is mentioned, please actively call this tool. This tool provides a structured workflow for component development following best practices. You must provide an absolute rootPath of workspace to save workflow files.
Inputs: fileId (required), layerId (required), rootPath (required), sourceLayerId.
mcp__getComponentLinkA
When the data returned by mcp__getDsl contains a non-empty componentDocumentLinks array, this tool is used to sequentially retrieve URLs from the componentDocumentLinks array and then obtain component documentation data. The returned document data is used for you to generate frontend code based on components.
Inputs: url (required).
mcp__getD2cA
使用此工具从 MasterGo 获取 D2C 数据,并在本地落盘: 1)将返回的 code 写入 html; 2)将返回的 svg / image 资源按 resourcePath 落盘到对应目录; 3)返回落盘摘要,避免把大体积资源塞进上下文。
Inputs: contentId (required), documentId (required), outDir.
mcp__getDesignSectionsA
[PRIMARY] This is the main tool for all designs. Operates in TWO modes:
Mode 1 — Get layout overview (sectionIndex NOT provided): Returns the list of all sections with id, name, type, nodeCount, and a page-absolute bounding box (x, y, width, height) for each section, plus totalSections and totalNodes. Also returns rootMetadata (root layer width/height/name/type/fill) when available. Use this FIRST to understand the design scope. The per-section bbox tells you exactly where each section sits inside the root container — use it for absolute positioning when generating code. Example: { "fileId": "123", "layerId": "456:789" }
Mode 2 — Get section DSL (sectionIndex provided): Returns the full DSL for ONE specific section.
PATH nodes have their svgHtml stripped. After fetching ALL sections, call mcp__getDesignSvgs to retrieve them.
IMPORTANT workflow:
First call WITHOUT sectionIndex to get the section list with node counts.
Then call WITH sectionIndex=0, sectionIndex=1, ... up to totalSections-1.
You MUST fetch ALL sections. Do NOT skip any section index.
CRITICAL: Fetch sections in BATCHES of 3-5 at a time. Do NOT request all sections simultaneously — too many concurrent requests will cause timeouts. Send 3-5 sectionIndex calls, wait for all results, then send the next batch.
After fetching all sections, call mcp__getDesignSvgs to get SVG icons.
Generate the complete HTML with all SVG data.
DO NOT call mcp__getDsl after completing this workflow — all data is already provided. If this tool returns an error (e.g. old server), fall back to mcp__getDsl.
You can provide either:
fileId and layerId directly, or
a short link (like https://{domain}/goto/LhGgBAK)
Inputs: fileId, format, layerId, shortLink, +2 more.
mcp__getDesignSvgsA
After fetching ALL sections via mcp__getDesignSections, call this tool to retrieve all cached SVG HTML strings. Each PATH node in the DSL has an id. Look up that id in the returned svgs map to get the complete SVG string. Insert the svgHtml string directly into HTML where icons should appear.
You can provide either:
fileId and layerId directly, or
a short link (like https://{domain}/goto/LhGgBAK)
Inputs: fileId, format, layerId, shortLink, +1 more.
mcp__getDesignTextsA
After fetching ALL sections via mcp__getDesignSections, call this tool to retrieve exact text content for large text nodes. In the section DSL, TEXT nodes with long content (>50 chars) have their "text" field replaced with a key like "T{sectionIndex}|{nodeId}". This tool returns the original text mapped by those keys. You MUST use the exact text from this response — never invent, paraphrase, or translate text.
You can provide either:
fileId and layerId directly, or
a short link (like https://{domain}/goto/LhGgBAK)
Inputs: fileId, format, layerId, shortLink, +1 more.
mcp__getDslA
[FALLBACK] Use only when mcp__getDesignSections is unavailable or returns an error. This returns the FULL DSL in one response — may be large and exceed context limits for complex designs. Prefer mcp__getDesignSections as the primary tool for all designs. You can provide either:
fileId and layerId directly, or
a short link (like https://{domain}/goto/LhGgBAK) This tool returns the raw DSL data that you can then parse and analyze. Use the optional 'format' parameter (json/yaml/tree, defaults to json) to control the serialization. This tool also returns the rules you must follow when generating code. The DSL data can also be used to transform and generate code for different frameworks.
Inputs: fileId, format, layerId, shortLink, +1 more.
mcp__getFlutterGeneratorA
Users need to actively call this tool to get the Flutter component development workflow. When Flutter Generator or Flutter Component is mentioned, please actively call this tool. This tool provides a structured workflow for Flutter component development following best practices. It includes MasterGo DSL to Flutter Widget mapping rules, screen adaptation with flutter_screenutil, and feature-based architecture guidance. It also downloads all image resources from the design file to local disk, rewrites CSS and DSL references to point at Flutter asset paths, and generates an asset manifest. You must provide an absolute rootPath of workspace to save workflow files.
Inputs: fileId (required), layerId (required), rootPath (required), featureName, +1 more.
mcp__getMetaB
Use this tool when the user intends to build a complete website or needs to obtain high-level site configuration information. You must provide a fileld and layerld to identify the specific design element. This tool returns the rules and results of the site and page. The rules is a markdown file, you must follow the rules and use the results to analyze the site and page.
Inputs: fileId (required), layerId (required), format, sourceLayerId.
version_0_2_2C
the current version is 0.2.2
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools have distinct purposes, but getDesignSections and getDsl overlap as primary and fallback for design data. Descriptions clarify the relationship, so confusion is minimal. The version tool and workflow tools are distinct.
All tools except version_0_2_2 follow the mcp__<action><Object> pattern with consistent camelCase. The version tool breaks the pattern but is a minor outlier.
12 tools is well-scoped for a design-to-code server covering extraction, generation, and linking. Each tool serves a clear role without redundancy.
The tool surface covers the full design-to-code pipeline: design section retrieval with supplementary SVG/text tools, DSL fallback, C2D and D2C conversion, component generators for multiple frameworks, and metadata. No obvious gaps for the stated purpose.
Maintenance
Related MCP Connectors
The Figma MCP server brings Figma design context directly into your AI workflow.
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Connect MCP clients to 2,000+ AI models without managing provider API keys.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that connects AI tools and LLMs to Figma designs, enabling them to extract design data, analyze design systems, and generate development documentation.1,123 npm2MIT
- -licenseNot gradedqualityNot gradedmaintenanceA server based on Model Context Protocol that processes and parses design files (Vextra/Figma/Sketch/SVG), enabling AI assistants to access and manipulate design content.3-
- AlicenseAqualityDmaintenanceConnects AI models with MasterGo design tools to retrieve and process DSL data from design files, enabling AI-powered design analysis and manipulation.214,435 npmISC
- AlicenseNot gradedqualityDmaintenanceConnects AI models to MasterGo design tools, enabling retrieval of DSL data, component documentation, and metadata from MasterGo design files for structured component development workflows.ISC