Moonvy UI MCP

An MCP for reading Moonvy design files, built for front-end development. Enter a project page or design file URL to get the page list, frame dimensions, layer tree, node styles, design tokens, and slice/snapshot/image-fill assets.

This project references the tool boundaries of lanhu-mcp, but reads data specifically from Moonvy: it extracts precise parameters from Moonvy's design data file (Genome) instead of guessing colors, font sizes, and spacing from screenshots.

What it can do

moonvy_get_node_style and moonvy_get_ui_spec provide:

• Absolute position, plus relativeX / relativeY relative to the parent node

• Distance to the parent node's right and bottom edges

• Width/height, visibility, opacity, and clipping state

• Solid color, gradient, and image fill references

• Font family, font size, font weight, line height, letter spacing, text color, and alignment

• Corner radius, strokes, and shadows

• A CSS property object you can reference directly

Related MCP server: Figma MCP

Data pipeline

Moonvy URL
  -> projectId / dirId / fileId
  -> POST https://global-api.moonvy.com/v2/anynode/get
  -> files.genome.url
  -> 下载并解压 Genome JSON
  -> 解析图层、样式、Token、资源
  -> MCP JSON 响应

Project/directory listing uses POST /v2/anynode/list. These are non-public endpoints currently used by the Moonvy web app. If Moonvy changes its endpoints or the Genome structure in the future, the adapter layer will need to be updated accordingly.

Installation

Requires Node.js 20 or higher.

cd C:\path\to\moonvy-ui-mcp
npm install
Copy-Item .env.example .env

Configure the Moonvy login token

1. Log in to Moonvy in your browser and open the Moonvy page you need to read.

2. Open the developer tools Console.

3. Run:

copy(window.app?.api?.$options?.token)

4. Write the copied value into this project's .env:

MOONVY_TOKEN=你的本机令牌

The token is stored only on your local machine. Don't send it to chat, commit it to Git, or write it into front-end code. The service responses proactively hide JWTs and resource URLs with query parameters.

Self-check

npm run check
npm test
npm start

npm start runs the stdio MCP service. Under normal conditions it won't print ordinary logs and will wait for an MCP client to connect.

Connecting to Codex / ChatGPT desktop app

In Settings, choose MCP servers -> Add server and select STDIO as the type:

• Command: node

• Arguments: C:\path\to\moonvy-ui-mcp\src\server.js

• Working directory: C:\path\to\moonvy-ui-mcp

You can also add the following to ~/.codex/config.toml or to .codex/config.toml inside a trusted project:

[mcp_servers.moonvy]
command = "node"
args = ["C:/path/to/moonvy-ui-mcp/src/server.js"]
cwd = "C:/path/to/moonvy-ui-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 180

The service reads MOONVY_TOKEN from .env under cwd by default. If you'd rather forward it from a local environment variable, you can also add:

env_vars = ["MOONVY_TOKEN"]

After saving, restart Codex/the desktop app and use /mcp in the input box to check the connection.

Connecting to Cursor / Windsurf / Claude Code

Use the standard stdio MCP configuration:

{
  "mcpServers": {
    "moonvy": {
      "command": "node",
      "args": ["C:/path/to/moonvy-ui-mcp/src/server.js"],
      "cwd": "C:/path/to/moonvy-ui-mcp"
    }
  }
}

Usage order for the current Moonvy link

Current link:

https://moonvy.com/project/89f75621-a0e7-4122-b9ee-b6b703e1c826/cf67c54c-8e2b-4809-9e4d-fc6512d0e0be

It contains projectId + dirId and points to a folder rather than a specific design file, so the recommended flow is:

1. Call moonvy_list_pages to get the file list.

2. Pick the specific design URL from the returned results.

3. Call moonvy_get_design to view the frame list.

4. Call moonvy_get_ui_spec on the target frame, starting with maxDepth=4 and maxNodes=500.

5. If you need to inspect a specific element precisely, first use moonvy_list_layers to find the node ID, then call moonvy_get_node_style.

6. Use moonvy_download_asset to download icons, background images, or page snapshots into the actual front-end project's asset directory.

Example prompt:

使用 Moonvy MCP 列出这个项目目录里的设计文件。找到“新增学生”页面后，
读取它的 UI spec，保留原始颜色、字号、间距和圆角，并把需要的切图下载到
C:/work/school-web/src/assets/moonvy。

Correspondence with lanhu-mcp

The current version focuses on "design -> front-end implementation" and does not replicate Lanhu's requirement-document analysis, team message board, or Feishu collaboration features.

Security and limitations

• Only use Moonvy projects you already have permission to access.

• .env is already in .gitignore; still, avoid committing the token manually.

• moonvy_download_asset requires an absolute output directory to prevent assets from being written to an unclear location by accident.

• You'll need to re-fetch the Moonvy token once it expires.

• This project does not bypass login, project permissions, or Moonvy server-side access controls.

• Fields in the Genome may not be fully consistent across different design tool versions; the parser keeps common compatibility fields, but we still recommend running an end-to-end acceptance test with your team's actual design files.

Development and testing

Unit tests use synthetic Genome data and don't require Moonvy credentials:

npm test

End-to-end testing against a real project requires a valid MOONVY_TOKEN:

1. moonvy_list_pages(文件夹 URL)
2. moonvy_get_design(设计文件 URL)
3. moonvy_get_ui_spec(设计文件 URL)
4. moonvy_get_node_style(设计文件 URL, 节点 ID)