Ardot MCP 使用说明

Ardot MCP Server 是腾讯设计 Ardot 提供的 Model Context Protocol 服务端实现，让 AI Agent（如 Claude、Cursor、Windsurf、CodeBuddy, WorkBuddy 等）能够直接读取和操作 Ardot 设计稿，实现设计与代码的双向联动。

Ardot MCP Server 帮助开发者更快速、更准确地探索和实现设计：

从 Ardot 设计文件获取设计上下文，支持基于设计稿进行读取、修改与生成
增强设计组件和 Code Connect 的工作方式（即将推出）

温馨提示： 目前 MCP 仅支持在 Ardot 桌面客户端中使用，无需安装客户端的云端版本 MCP 正在加紧开发中，敬请期待～

快速开始

1. 准备可用环境

使用支持 MCP 服务器的 AI Agent 或代码编辑器，例如 CodeBuddy、WorkBuddy、Cursor、Claude Code、Codex 等。
推荐优先使用 CodeBuddy 或 WorkBuddy。

2. 访问 Ardot 官网并登录

访问 Ardot 官网注册登录。
下载桌面端，并在客户端中打开任意设计文件。

下载 Ardot 桌面端

平台	芯片/架构	下载地址
macOS	Apple Silicon (M1/M2/M3/M4)	Ardot_latest_macOS_arm64.dmg
macOS	Intel	Ardot_latest_macOS_x86_64.dmg
Windows	桌面端	即将推出

Ardot 同时支持 macOS 桌面端和 Web 端（PC 浏览器），Ardot MCP 优先支持 macOS 桌面端。

如何使用 MCP Server

MCP Server 配置入口

点击 Ardot 首页右上角的 MCP 配置入口。
在配置弹窗中开启您所需的代码编辑器。
打开任意 Ardot 设计文件，检查服务连接是否正常。
在终端对话中输入您想要的设计内容。

示例提示词：

使用 Ardot，设计一个健身 App，为健身追踪 App 设计完整的用户注册流程和运动数据看板页面，支持图表展示每日运动数据。

输入设计内容示例

MCP 工具列表

Ardot MCP Server 提供以下 18 个工具（更多 API 持续更新中）：

查询类

工具名	说明
`fetch_editor_state`	获取当前编辑器状态，包括活跃画布、用户选区、打开的文件等基本信息，适合在开始设计任务前了解当前上下文
`fetch_file_info`	获取当前活跃设计文件的基本信息，包括文件名、文件链接、文件 ID 以及当前用户的访问权限，可在执行编辑操作前确认是否具备写入权限
`batch_read`	批量检索节点——支持按 `name`/`type` 正则模式搜索、按节点 ID 精确查找，可控制返回层级深度和数据详细程度，并支持按需返回指定属性
`capture_screenshot`	获取指定节点或画布区域的截图，用于验证 AI 生成的布局是否正确、检查视觉效果和组件外观，支持批量截图（建议单次不超过 10 个）
`capture_layout`	获取设计文件的布局结构树，支持按深度限制返回范围，可仅返回存在重叠、裁剪等布局问题的节点

设计系统

工具名	说明
`fetch_variables`	读取设计文件中定义的变量（Design Token），包括颜色、间距、字号等，可用于生成 CSS 全局样式规则
`apply_variables`	创建或更新设计变量集合，支持多模式（如 Light/Dark），支持 COLOR、FLOAT、BOOLEAN、STRING 四种变量类型，默认合并模式
`fetch_component_lib`	获取本地组件库中的组件与组件集合，便于在通过 `batch_edit` 创建实例前先发现可复用组件
`fetch_guidelines`	获取不同主题设计规范指引，支持 7 个主题：`table`（表格）、`landing-page`（落地页）、`web-app`（Web 应用）、`mobile-app`（移动端）、`slides`（幻灯片）、`code`（代码生成）、`tailwind`（Tailwind CSS v4）
`search_style_guide`	跨多个设计领域（风格、配色、字体、布局）搜索风格指南候选项，为落地页、营销站、看板或应用界面等设计任务提供创意方向与视觉灵感
`build_style_guide`	基于 `search_style_guide` 的选择结果构建完整设计系统，输出包含颜色、字体、间距、效果等参数的 Markdown 设计规范

编辑操作

工具名	说明
`batch_edit`	批量执行设计操作，支持 6 种操作类型：Insert（插入）、Copy（复制）、Update（更新）、Move（移动）、Delete（删除）、Image（生成/获取图片），每次调用建议不超过 25 个操作
`locate_available_space`	在画布中按指定方向（上/右/下/左）和尺寸查找空白区域，可指定起始参考节点和最小间距，用于放置新设计内容
`create_new_page`	在当前 .ardot 文件中新增一个空白页面（CANVAS），可指定页面名称、插入位置以及是否切换焦点至新页面

资源与导出

工具名	说明
`scan_exportable_resources`	扫描节点树并按类型返回可导出的资源节点（image、svg），用于在调用 `export_nodes` 前确定导出范围与格式
`export_nodes`	将节点导出为 PNG、JPEG、WEBP、SVG、PDF 等格式的图像文件，PDF 模式可将多个 Frame 合并为单个文件
`upload_images`	批量上传本地图片文件并将其作为图像填充应用到指定节点，支持 PNG、JPEG、WEBP，单次最多 20 项

辅助工具

工具名	说明
`get_available_fonts`	获取当前环境中可用的字体列表及其样式，用于在创建文本节点后验证字体是否可用，确保使用正确的 `fontName`（family + style）组合

使用场景

设计稿转代码

用户：基于当前设计稿的登录页面，帮我生成 React 组件代码
AI：[调用 fetch_editor_state 获取当前状态]
    [调用 capture_screenshot 获取页面截图]
    [调用 batch_read 获取图层结构和属性]
    [调用 fetch_guidelines 获取代码生成规范]
    → 生成完整的 React 组件代码

AI 辅助设计

用户：在当前画布右侧创建一个 Dashboard 页面
AI：[调用 locate_available_space 找到空白区域]
    [调用 fetch_guidelines 获取 Web 应用设计规范]
    [调用 batch_edit 创建页面结构和组件]
    [调用 capture_screenshot 验证设计效果]
    → 完成 Dashboard 页面设计

设计系统管理

用户：为项目创建一套亮色/暗色主题的设计变量
AI：[调用 fetch_variables 查看现有变量]
    [调用 apply_variables 创建颜色、间距、字号等 Token]
    → 完成设计变量定义

设计审查

用户：检查当前页面是否存在布局问题
AI：[调用 capture_layout 并设置 problemsOnly=true]
    → 返回所有存在对齐/溢出问题的节点

常见问题

MCP Server 连接失败？

确认 Ardot 编辑器已打开并加载了设计文件
检查 AI 工具的 MCP 配置是否正确
重启 AI 编程助手重新建立连接

batch_edit 操作报错？

确保每个 Insert / Copy / Replace 操作都有绑定名
单次调用不超过 25 个操作
不要对刚复制的节点的子节点使用 Update，因为子节点 ID 会重新生成

截图为空或不完整？

确认 nodeId 指向的节点在画布可见范围内
检查节点是否有实际内容（空 frame 不会产生有意义的截图）

Ardot MCP 使用说明 ​

Ardot MCP Server 帮助开发者更快速、更准确地探索和实现设计： ​

快速开始 ​

1. 准备可用环境 ​

2. 访问 Ardot 官网并登录 ​

下载 Ardot 桌面端 ​

如何使用 MCP Server ​

MCP Server 配置入口 ​

MCP 工具列表 ​

查询类 ​

设计系统 ​

编辑操作 ​

资源与导出 ​

辅助工具 ​

使用场景 ​

设计稿转代码 ​

AI 辅助设计 ​

设计系统管理 ​

设计审查 ​

常见问题 ​

MCP Server 连接失败？ ​

batch_edit 操作报错？ ​

截图为空或不完整？ ​