mcp-sketch
mcp-sketch
English | 中文
MCP 服务 & CLI:把 Sketch Meaxure 导出的设计稿(zip 或目录)解析成结构化图层数据,配合 AI 编码工具(Claude Code / OpenCode 等)高效还原设计稿页面。
建议使用多模态模型(需要查看画板预览图理解布局)
与 AI 直接读设计稿相比
新一代模型直接读解压后的文件也能还原得不错,贵的是取数过程本身。mcp-sketch 把取数工具化,省 token 也省 AI 的工作:
维度 | AI 直接读解压文件 | mcp-sketch |
取数方式 | 反复试探:解压、翻目录找入口、读 html 猜内嵌变量 | 一次调用拿到过滤、排序后的结构化图层 |
输出密度 | 原始大 JSON 照单全收 | 定位数组 + 噪音过滤;重复图层无损折叠省约一半 |
按需取数 | 只能整文件读 |
|
文本与样式 | 看图猜字,从大 JSON 里捞样式 |
|
切图与预览 | 自己找图处理、翻 preview 目录 | webp 自动导出全局去重;预览图直接给出 |
重复成本 | 每次会话重复全部过程 | 结果落盘缓存,设计稿没变不重算 |
还原度检查 | 肉眼对比两张图 | compare 相似度分数 + 差异图,量化收敛 |
亮点:布局权重降序(-l 20 先拿骨架)· 设计 token 按频次聚合(直接建主题变量、发现近似色笔误)· 缓存自愈(设计稿更新或切图被清理自动重算)。
一句话:模型负责还原,工具负责喂料。省下试探取数的 token,全部花在写代码上。
Related MCP server: codesign-mcp
2.x 能力
四个工具,CLI 与 MCP 双形态(参数一致):
能力 | CLI | MCP 工具 |
画板概览 |
|
|
图层解析 |
|
|
开发服务 |
|
|
截图对比 |
|
|
list — 画板概览
输出全部画板的名称、预览图路径、图层数据量(
size按 analyze 同口径估算,用于估算单次取数量、决定是否按区域分批),写入.sketch-cache/{design}/list.json附带设计 token 聚合:颜色 / 字号 / 字体 / 圆角 / 阴影 / 命名样式按使用频次排序,可直接用于建立主题变量,也能发现设计稿里的近似色号笔误
切图占比在全部画板中断档领先(≥ max(10%, 中位数×3))的画板标记
sliceBoard: true(疑似标记,AI 结合预览图确认)——设计师把切图集中成一个画板的常见习惯,这类画板不是待还原页面设计稿更新后不会返回过期缓存:发现设计稿比 list.json 新则重新生成
analyze — 图层解析
图层按布局权重(面积为主)降序返回,已过滤无视觉属性的图层
过滤与分页:区域矩形
rect、排除区域exclude_rects、名称关键词name、类型type(text/shape/slice)、limit/offset,返回total总数便于翻页输出为省 token 的定位数组格式:
columns一次性声明列序,每个图层一行按位读取大面积重复图层(表格单元格/列表项等)自动折叠——无损压缩,表格类画板输出可省约一半
css承载主要样式声明(字体/颜色/渐变/圆角/阴影,默认值噪音已过滤);assets为纯路径数组(相对项目根目录,已压缩为 webp,可直接 import)slice图层自动导出切图,同内容全局去重(跨画板共享的图标只存一份);自动生成画板预览图,区域查询时生成对应区域的裁剪预览
dev — 开发服务
后台启动 dev server,轮询配置的
PREVIEW_URL直到可访问;已在运行则直接返回
compare — 截图对比
纯两图差异器:
-b基准图(设计侧)与-s实现截图(页面侧)逐像素比对,返回相似度分数与差异放大图,支持"改代码 → 截图 → 对比 → 修正"的量化收敛循环基准图来源:整页比对用
list返回的画板previewPath;单个组件用analyze -r返回的区域previewPath(已按 rect 裁剪),配合 playwright-cli 元素截图(screenshot "{selector}")即可做组件级比对浏览器截图由 playwright-cli 完成(纯命令行,无需 MCP 配置与重启会话,见下方安装)
使用
安装 skill(推荐)
npx -y mcp-sketch install交互选择平台,写入对应目录:
平台 | skill 目录 |
Claude Code |
|
OpenCode |
|
skill 会教 AI 在什么时机、用什么参数调用上述工具(含 /sketch init 了解项目并检查 sketch 相关配置(.env.sketch、.gitignore 缓存忽略、playwright-cli 可用性)、/sketch overview 概览设计稿、/sketch draw 绘制页面三个固定指令),已存在的文件可逐文件选择覆盖或跳过。
配置 MCP 服务
设置 MCP_MODE=1,在 AI 工具中配置为本地 MCP 服务:
opencode
{
"mcp": {
"mcp-sketch": {
"type": "local",
"command": ["npx", "-y", "mcp-sketch"],
"enabled": true,
"environment": { "MCP_MODE": "1" }
}
}
}claude code
{
"mcpServers": {
"mcp-sketch": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-sketch"],
"env": { "MCP_MODE": "1" }
}
}
}安装 playwright-cli(compare 截图依赖,可选)
compare 的输入是浏览器截图,由 playwright-cli 打开页面、探索渲染结果并截图,纯命令行驱动,无需 MCP 配置、无需重启会话:
# 方式一:全局安装
npm install -g @playwright/cli@latest
playwright-cli install # 安装默认浏览器 chromium(下载量大)
# 方式二:npx 免安装,两种方式的命令等价(playwright-cli → npx -y @playwright/cli)
npx -y @playwright/cli install私有镜像仓库同步滞后导致
@latest拉取失败时,用npm view @playwright/cli versions --json查可用版本,降级用npx -y @playwright/cli@<版本>重试使用系统浏览器通道(
open时配--browser=msedge或chrome)可跳过浏览器安装需要登录态的页面:
attach --extension=chrome接管自己的浏览器,或open --persistent用持久化配置目录
直接使用 CLI
未全局安装时用
npx -y mcp-sketch <cmd>;频繁使用建议npm i -g mcp-sketch(避免 npx 每次查询 registry 的冷启动延迟)
# 画板概览(生成 list.json 与全部预览图)
mcp-sketch list -f "设计稿.zip"
# 图层解析:整个画板前 20 个图层
mcp-sketch analyze -f "设计稿.zip" -p "页面名" -a "画板名" -l 20
# 区域解析:登录框区域,排除子组件占位区
mcp-sketch analyze -f "设计稿.zip" -p "页面名" -a "画板名" -r "[695,200,530,660]" -e "[[700,600,120,40]]"
# 按名称/类型快速定位
mcp-sketch analyze -f "设计稿.zip" -p "页面名" -a "画板名" -n "logo"
mcp-sketch analyze -f "设计稿.zip" -p "页面名" -a "画板名" -t text
# 截图对比(-b 基准图:画板/区域预览图;-s 实现截图)
mcp-sketch compare -b "preview.webp" -s "screenshot.png"
mcp-sketch <cmd> --help查看完整参数
配置
项目根目录 .env.sketch(可选):
字段 | 必填 | 默认值 | 说明 |
| 否 |
| dev 服务启动命令 |
| 否 | - | dev 服务地址,使用 |
| 否 | 当前目录 | 项目根目录 |
| 否 |
| 切图输出路径 |
| 否 | 开启 | 重复图层折叠开关,配 |
| 否 |
| 日志级别 |
Linux / macOS / WSL 使用
dev命令需安装 tmux:brew install tmux(macOS) /sudo apt install tmux(Ubuntu/Debian/WSL),Windows 无需额外安装
输出目录
.sketch-cache/{设计稿名}/list.json # 画板列表 + 设计 token
.sketch-cache/{设计稿名}/analyze/ # analyze 结果缓存({页面}--{画板}--{参数}--{hash}.json)
.sketch-cache/assets-index.json # 切图内容索引(全局去重 + 拼音名 → 原始文件名/图层溯源)
.sketch-cache/{设计稿名}/{页面}/{画板}/ # 画板/区域预览图(webp)
.sketch-cache/{设计稿名}/{页面}/{画板}/compare/ # 对比差异图({timestamp}.webp)
.sketch-cache/{设计稿名}/{页面}/{画板}/screenshot/ # 浏览器截图(AI 按 skill 约定保存)
{ASSETS_PATH}/{页面拼音}/{画板拼音}/ # 切图(webp,全局去重)2.x 与 1.x 的关系
1.x 是一整套多 agent 智能体流水线(拆分组件、生成代码、审核);2.x 放弃了它——模型已经足够强,直接读解压后的设计稿文件也能还原得不错,剩下的痛点只有取数。2.x 只做这一件事:把取数工具化,把还原的决策交还给模型。
想继续使用 1.x:安装与 MCP 配置的命令改为
npx -y mcp-sketch@1,并把已安装 agents / skills 内的npx -y mcp-sketch全局替换为npx -y mcp-sketch@1
Available Tools
1 toolsketch_html_analyzesketch_html_analyzeC
Analyze sketch html files and return the design structure of corresponding pages or drawing boards
Inputs: file_path (required), page_id, page_name, artboard_id, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool in the set, there is no possibility of confusion or overlap with other tools within this server.
The single tool uses clear snake_case with a descriptive verb suffix, but with only one data point, a broader naming pattern cannot be established.
A single analysis tool is too few for the apparent scope implied by the server name 'mcp-sketch', suggesting a severely limited integration surface.
The server only supports analyzing HTML exports, lacking any functionality for creating, editing, or exporting native Sketch files, representing significant gaps for design workflow automation.
Maintenance
Related MCP Connectors
MCP server for web extraction and rendering via AceDataCloud WebExtrator
MCP server to assist with JxBrowser development.
A remote MCP server to convert HTML documents (URL or raw source) to PDF or screenshots
Document conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceMCP server to provide Sketch layout information to AI coding agents like Cursor71MIT
- AlicenseAqualityBmaintenanceLocal MCP server for Tencent CoDesign sharing links, exposing artboards, layer specs, preview images, and exported slices to support design-to-code workflows.860 npm23MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for ingesting UI screenshots, Figma MCP node JSON, or hybrid Figma-plus-screenshot sources into a cross-platform design-to-code artifact pipeline.109 npmMIT
- AlicenseNot gradedqualityBmaintenanceMCP server for the MiroMiro design-extraction API. It extracts real design data from live websites—including brand colors, fonts, tokens, SVGs, images, and component code—so AI agents can build from actual values.165 npmMIT