Skip to main content
Glama
MasterGo Magic MCP

MasterGo Magic MCP

Official

MasterGo Magic MCP

MCP Toplist

Ask DeepWiki

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

  1. Visit https://mastergo.com

  2. Enter personal settings

  3. Click the Security Settings tab

  4. Find the personal access token

  5. Click to generate the token

Permission Requirements

Important: If the tool is connected but returns a "no permission" error, please check the following conditions:

  1. Account Version Requirement:

    • Requires Team Edition or higher MasterGo account

    • Personal free edition does not support MCP tool access

  2. 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 supports HTTPS_PROXY / HTTP_PROXY environment 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 — including Content-Type and the auth token — so match the default key exactly when overriding. Also settable via the MG_EXTRA_HEADERS environment 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 of json (default), yaml, tree. An explicit per-call format tool parameter overrides this. Also settable via the DEFAULT_FORMAT environment variable.

  • --debug (optional): Enable debug mode for detailed error information

  • --no-rule (optional): Disable default rules

  • --no-prefix (optional): Register tools without the mcp__ name prefix (e.g. getDsl instead of mcp__getDsl). Some MCP clients (such as Grok Build) silently skip tools whose fully-qualified server__tool name contains more than one __ separator — since the server is already prefixed, a mcp__getDsl tool name becomes server__mcp__getDsl and is dropped. Enable this flag for those clients. Also settable via the MG_NO_PREFIX environment 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" --debug

Environment Variables

Alternatively, you can use environment variables instead of command line arguments:

  • MG_MCP_TOKEN or MASTERGO_API_TOKEN: MasterGo API token

  • API_BASE_URL: API base URL

  • RULES: JSON array of rules (e.g., '["rule1", "rule2"]')

  • DEFAULT_FORMAT: Default output format for design-data tools (json | yaml | tree); the --format argument and an explicit per-call format tool parameter take precedence.

  • MG_NO_PREFIX: Set to 1/true/yes to register tools without the mcp__ name prefix (the --no-prefix argument takes priority).

  • HTTPS_PROXY / https_proxy / HTTP_PROXY / http_proxy: HTTP(S) proxy URL (the --proxy argument 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

json

Default. Compact JSON — useful when piping output into tools that expect JSON. Byte-identical to the prior behavior.

yaml

Fewer tokens than JSON for typical designs (flat layouts with repeated values benefit most).

tree

Experimental compact format. Structural keys (id, name, type) are encoded positionally on each node line, and style values stay deduplicated in a globalVars block. Designs with heavy style reuse see the largest token savings.

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:

  • tree applies to all six tools' responses: mcp__getDesignSections (section list and per-section DSL), mcp__getDsl, mcp__getDesignSvgs, mcp__getDesignTexts, mcp__extractSvg, and mcp__getMeta. mcp__getMeta falls back to JSON under tree because its rules field 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, json is 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 format value falls back to json.

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

  1. Visit Smithery Marketplace

  2. Click the "Connect" or "Install" button

  3. Select your MCP client (e.g., Claude Desktop, Cursor, etc.)

  4. 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 tools

  • http-util.ts: Utility for handling HTTP requests to the MasterGo API

  • types.d.ts: TypeScript type definitions for the project

src/tools

Contains implementations of MCP tools:

  • base-tool.ts: Base class for all MCP tools

  • get-dsl.ts: Tool for retrieving DSL (Domain Specific Language) data from MasterGo design files

  • get-component-link.ts: Tool for retrieving component documentation from links

  • get-meta.ts: Tool for retrieving metadata information

  • get-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 usage

  • component-workflow.md: Component development workflow documentation guiding structured component development process

Local Development

  1. Run yarn and yarn build to install dependencies and build the code

  2. Find the absolute path of dist/index.js

  3. Add 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": {}
},
  1. 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 tools
mcp__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:

  1. fileId and layerId directly, or

  2. 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__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:

  1. First call WITHOUT sectionIndex to get the section list with node counts.

  2. Then call WITH sectionIndex=0, sectionIndex=1, ... up to totalSections-1.

  3. You MUST fetch ALL sections. Do NOT skip any section index.

  4. 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.

  5. After fetching all sections, call mcp__getDesignSvgs to get SVG icons.

  6. 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:

  1. fileId and layerId directly, or

  2. 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:

  1. fileId and layerId directly, or

  2. 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:

  1. fileId and layerId directly, or

  2. 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:

  1. fileId and layerId directly, or

  2. 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

    A3.6/5.0

    Scored across 12 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    12 tools is well-scoped for a design-to-code server covering extraction, generation, and linking. Each tool serves a clear role without redundancy.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A 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
      -
    • A
      license
      A
      quality
      D
      maintenance
      Connects AI models with MasterGo design tools to retrieve and process DSL data from design files, enabling AI-powered design analysis and manipulation.
      2
      14,435 npm
      ISC