Design MCP

Design MCP (Model Context Protocol) is a standardized interface provided by Tencent Design that allows AI agents and coding assistants to directly read and operate on design file data, enabling seamless design-to-code workflows.

What is Design MCP

Design MCP is built on the Model Context Protocol specification. By running an MCP Server locally, tools like Claude, Cursor, and Windsurf can:

• Read layer structure, properties, and styles from the canvas
• Capture design screenshots
• Query design system variables and Style Guide
• Create, modify, and delete layers

Architecture Overview

AI Agent (Claude Desktop / Cursor / Windsurf)
        ↓  MCP Protocol (stdio)
  Gateway Server (local process, port 50501)
        ↓  Socket.io
   Relay Server (forwarding layer)
        ↓  WebSocket
  Tencent Design editor (browser/client)
        ↓  Adapter
     Editor engine

Component breakdown:

Component	Location	Responsibility
Gateway Server	packages/common/design-mcp/gateway-server	Receives MCP requests from AI agents, forwards to Relay Server
Relay Server	packages/common/design-mcp/relay-server	Bridges messages between Gateway and the editor
Adapter	packages/common/design-mcp/adapter	Executes actual layer operations inside the editor
VS Code Extension	packages/frontend/vscode-extension	Provides IDE integration

---

Quick Setup

Prerequisites

• Node.js >= 20
• Tencent Design desktop app installed, or design file open in a browser

Install and Start

# Install the MCP package
npm install -g @tencent/cocraft-design-mcp

# Start the Gateway Server (fixed port 50501)
cocraft-mcp --port 50501

Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cocraft": {
      "command": "node",
      "args": ["/path/to/dist/gateway-server/cli.mjs", "--port", "50501"],
      "type": "stdio"
    }
  }
}

Configure Cursor

Add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "cocraft": {
      "command": "node",
      "args": ["/path/to/dist/gateway-server/cli.mjs", "--port", "50501"]
    }
  }
}

Connect the Editor

Open a design file with the ?embed=true parameter to connect the editor to the Relay Server automatically:

http://localhost:5800/file/{file_id}?embed=true

---

MCP Tool Reference

Design MCP provides 15 tools:

Query

Tool	Description
get_editor_state	Get current editor state (open file, selected nodes)
batch_get	Batch query nodes — supports name/type regex search
get_screenshot	Capture a screenshot of a node or the entire canvas
snapshot_layout	Get a layout structure snapshot (nested hierarchy)
search_all_unique_properties	Search unique property values (colors, fonts, etc.)

Design System

Tool	Description
get_style_guide	Get design system Style Guide (colors, typography, spacing)
get_style_guide_tags	Get Style Guide tag categories
get_variables	Read design variables (Design Tokens)
set_variables	Write design variables
get_guidelines	Get code guidelines (code/table/tailwind formats)

Edit Operations

Tool	Description
batch_design	Batch design operations: Insert/Copy/Update/Replace/Move/Delete
open_document	Open a .pen file or create a new document
find_empty_space_on_canvas	Find empty space on the canvas for inserting new content
replace_all_matching_properties	Global property replacement (e.g., bulk color change)
update_properties	Update properties of specific nodes

---

Usage Examples

With Claude connected, you can do things like:

Read design data:

User: Get the styles of all Button components in the current design file
Claude: [calls batch_get, searching by type=COMPONENT for Button]

Generate code:

User: Based on the login page design, generate a React component
Claude: [calls get_screenshot + batch_get to get layout info, generates code]

Batch edit:

User: Replace all instances of #0052D9 with #FF4D4F in the design
Claude: [calls replace_all_matching_properties]

Read design variables:

User: Get all color tokens from the design file
Claude: [calls get_variables, returns all variable collections]

Export code guidelines:

User: Output the spacing spec in Tailwind CSS format
Claude: [calls get_guidelines with format=tailwind]

---

Debugging

Use the MCP Inspector to debug:

pnpm mcp:debug
# or
npx @modelcontextprotocol/inspector node /path/to/dist/gateway-server/cli.mjs

Open http://localhost:5173 in your browser to visually test each tool's calls and responses.

During development, use watch mode to auto-recompile on changes:

pnpm watch

---

VS Code Extension Integration

After installing the Tencent Design VS Code extension, Design MCP syncs automatically with the editor:

1. Run CoCraft: Open Webview from the VS Code command palette
2. Run CoCraft: Set File ID to bind the target design file
3. The MCP Gateway automatically connects to the bound file

Once bound, AI coding tools like Cursor can reference your design directly — no manual window switching required.