@mastergo/magic-mcp weekly downloads statistics

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

Tutorial

• https://mastergo.com/file/192644601973042

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.