mcp-sketch

English | Chinese

A local tool providing both MCP server and CLI modes to parse HTML zip archives exported from Sketch-Meaxure and extract design structure information.

SKILL

• It is recommended to download the sketch-html skill and customize your own version to analyze zip files exported from Sketch-Meaxure.

• You can also use the skills tool to download it.

npx skills@latest add YamadaAoi/mcp-sketch -s sketch-html

Related MCP server: codesign-mcp

Disclaimer

• To avoid confusing the AI, this tool filters out some meaningless layers, but it does not rule out the possibility of filtering out some valid layers.

• It is recommended to communicate with UI designers; for complex effects, try to use sliced images; for simple effects, set a radius for emphasis, even if it is just 1.

Features

• Parse Sketch exported HTML zip archives and extract design structure

  • Supports filtering by page and artboard

  • Supports parsing specified rectangular areas

  • Outputs design structure JSON and preview images for AI reference

• Provides both MCP server and CLI usage modes

Usage

Method 1: Direct CLI Usage

Use with npx:

npx -y mcp-sketch analyze -p /path/to/export.zip

Command Options

CLI Example

If parameters contain spaces, they must be enclosed in quotes

# 分析 zip 中第一个页面第一个画板
npx -y mcp-sketch analyze -p "/path/to/export .zip"

# 分析指定页面
npx -y mcp-sketch analyze -p /path/to/export.zip --pn 首页

# 分析指定页面指定画板
npx -y mcp-sketch analyze -p /path/to/export.zip --pn 首页 --an 用户管理

# 分析指定区域
npx -y mcp-sketch analyze -p /path/to/export.zip --pn 首页 --an 用户管理 -r "[0,0,1920,64]"

Method 2: MCP Server

You must set the environment variable MCP_MODE=1 to enable the MCP server. Configure it as a local MCP server to allow AI tools to call it directly.

• opencode:

{
  "mcp": {
    "mcp-sketch": {
      "type": "local",
      "command": ["npx", "-y", "mcp-sketch"],
      "enabled": true,
      "environment": {
        "MCP_MODE": "1",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

• Trae:

{
  "mcpServers": {
    "mcp-sketch": {
      "command": "npx",
      "args": ["-y", "mcp-sketch"],
      "env": {
        "MCP_MODE": "1"
      }
    }
  }
}

MCP Parameters

Use the sketch_html_analyze tool to analyze the HTML zip archive exported from Sketch:

MCP Call Examples

• Analyze the first artboard of the first page in the Sketch HTML zip archive:

sketch_html_analyze({ file_path: "/path/to/export.zip" })

• Analyze the first artboard of a specified page:

sketch_html_analyze({ file_path: "/path/to/export.zip", page_name: "首页" })

• Analyze a specified artboard on a specified page:

sketch_html_analyze({ file_path: "/path/to/export.zip", page_name: "首页", artboard_name: "用户管理" })

• Analyze a specified area of a specified artboard on a specified page, e.g., parsing the top navigation bar of a user management artboard:

sketch_html_analyze({ file_path: "/path/to/export.zip", page_name: "首页", artboard_name: "用户管理", rect: [0, 0, 1920, 64] })

Parameter Priority

• page: page_id > page_name > first page

• artboard: artboard_id > artboard_name > first artboard

• rect: Specifies the rectangular area to parse. The filtering rule is that as long as the element's x, y, x+width, y+height are within the rectangle, it will be parsed.

Return Results

The tool returns text: {artboard: {analysis_result}, previewPath: "preview_image_path"}

• artboard

  • Artboard data, including layers, styles, images, and other information

• previewPath

  • Uses sharp as an optionalDependencies for image processing.

  • If installation fails (extreme case, as sharp depends on libvips), the original full artboard image will be returned.

  • If installation succeeds, it will resize, crop the rect area (if specified), and compress it into webp format.

  • Only processes preview images; does not handle sketch slices.

Output File Location

• Parsed sliced images are saved in the src/assets/sketch/ directory by default (can be customized via assets_path)

• Parsed design content is saved to a local JSON file by default (for manual review), stored in a folder with the same name as the zip file at the same level

Usage Suggestions

• Use models that support multi-modality to read preview images and correct the design structure

• Keep the data volume provided to the AI under 50KB to improve AI analysis accuracy (the locally stored JSON file is formatted, while the data passed to the AI is in a compact format)

• It is recommended to use the rect parameter to parse specific areas within an artboard for modular development and improved granularity.

Guide