更新时间：2026年10月20日

Pixso MCP 可以通过远程服务、桌面端本地服务或 IDE 插件连接 Codex、Cursor 等 AI 工具。先选接入方式并完成授权，再提供准确的图层链接，最后用一次只读任务确认对象。远程接入不要求 Pixso 网页或客户端一直打开；本地接入则需要保持提供服务的一端运行。

在完整产品链路中，Paico 更适合把一句需求快速变成可交互方案；进入专业设计、设计系统和工程交付后，再由 Pixso 与 D2C/C2D/MCP 承接。明确分工，能减少把需求探索、设计协作和代码验收混在一次调用里的问题。

通过Pixso MCP 连接设计与 AI 编程工具后，可以围绕目标图层读取结构、修改设计或辅助生成代码。协议原理、数据类型和团队使用方式见Pixso MCP 设计到代码原理与落地指南。

使用 Pixso MCP 前需要准备什么？

先准备有访问权限的设计文件、一个完整业务容器，以及支持 Streamable HTTP 的 IDE 或 Agent。要生成代码，还需要打开目标仓库并确定框架、组件目录与样式方案。先拿一张卡片或一个表单试通，比一次提交整个大型文件更容易定位问题。

调用 MCP 需要全功能席位或研发席位，读取目标文件需要可查看权限，修改设计还需要可编辑权限。D2C+ 设计转代码另外要求企业版全功能或研发席位，并使用企业空间文件；企业空间内的文件（包括该空间下的个人草稿）可使用，非企业空间文件不可使用。权限说明见Pixso MCP 工具与指令。

Pixso MCP的远程、本地和IDE插件三种接法，以及读取、设计修改和代码验收顺序

身份与服务：远程接入完成 OAuth 授权；本地接入开启客户端或 IDE 插件中的 MCP 服务，并核对实际地址。
IDE 或 Agent：Cursor、VS Code 等支持 HTTP MCP 的客户端可按各自配置格式连接；Windsurf、Claude Code、Codex 的字段或命令以当前版本为准。
设计对象：优先选择完整 Frame、Section 或语义清楚的容器；使用“画布选中”方式时，一次只选一个容器。
代码上下文：先打开目标仓库，并准备项目框架、组件目录、样式方案、路由和资源存放位置。

如果尚未安装客户端，可先下载最新版 Pixso 客户端。不要把账号密码、接口密钥、生产环境配置或客户敏感数据写进提示词。

远程、本地和 IDE 插件，应该选哪一种？

不想让设计客户端一直开着，选远程 MCP；需要操作当前画布选区，选本地 MCP；希望设计画布和代码在同一窗口中，选 Pixso IDE 插件。三种接法都要确认目标文件和账号权限，区别主要在服务运行位置、文件定位方式与操作环境。

接入方式	连接地址	使用条件	适合的任务
远程 MCP	`https://pixso.cn/mcp`	完成 OAuth 授权，提供带 `item-id` 的图层链接；不必保持 Pixso 网页或客户端开启	让 Agent 按明确链接读取、检查或修改指定设计
桌面端本地 MCP	默认 `http://127.0.0.1:3667/mcp`，以客户端显示地址为准	同机客户端已登录并启用服务，目标文件页签保持激活	围绕当前选区边设计、边调用工具
Pixso IDE 插件	`http://127.0.0.1:3667/mcp`	在兼容 IDE 安装并登录 Pixso 插件，选定目标文件	在 IDE 内查看画布，讨论和修改同一个设计对象

本地地址中的 127.0.0.1 指调用工具所在的电脑。远程运行的 Agent 不能用这个地址访问你桌面上的 Pixso。私有化环境应使用本企业的内网服务地址，并确认 Agent 能访问该网络，不要把内网文件链接发给公网服务。

如何通过远程 MCP 连接 Codex 和 Cursor？

远程接入先完成授权，再核对图层。使用支持 Streamable HTTP 和 OAuth 的客户端时，只需添加服务地址，不需要在提示词中粘贴个人访问令牌。

在 Codex 中添加远程服务

进入设置中的插件或 MCP 管理页面，添加服务器。
选择流式 HTTP，名称可填 pixso-remote，URL 填 https://pixso.cn/mcp。
保存后点击连接或认证，完成 Pixso 授权登录。确认授权账号有权访问目标设计文件。
回到 MCP 列表，查看连接状态和工具列表，再进行下方的首次读取测试。

使用 Codex CLI 时，也可以添加服务并启动授权：

codex mcp add pixso-remote --url https://pixso.cn/mcp
codex mcp login pixso-remote
codex mcp list

桌面界面和 CLI 是两种配置入口，不要为同一条路线重复添加多个同名服务。CLI 的 OAuth 登录与配置选项可查阅 Codex MCP 配置文档。

在 Cursor 中配置远程服务

打开 Settings 中的 MCP 设置，新建服务器，将下列内容加入 mcp.json，保存后完成客户端弹出的 OAuth 授权：

{
  "mcpServers": {
    "pixso-remote": {
      "url": "https://pixso.cn/mcp"
    }
  }
}

若服务能列出工具，但目标文件返回权限错误，应检查授权账号和文件权限，不要反复重装 IDE。需要用访问令牌接入时，按 Pixso 远程 MCP 配置设置对应客户端的凭证字段；令牌不能提交到代码仓库、聊天记录或共享截图中。

如何在 Pixso 客户端启用 MCP？

本地路线需要先打开设计文件，在顶栏左上角的 MCP 配置入口开启服务，再复制当前显示的地址。下面的本地流程图只适用于这条路线，不是远程 MCP 的启动条件。

启动并登录 Pixso 客户端。
新建或打开一个设计文件，让目标页面处于当前激活页签。
打开设计文件顶栏左上角的 MCP 配置入口，开启服务开关。
复制客户端实际显示的地址。默认端口是 3667，端口被 IDE 插件等占用时可能变化。

Pixso 设计稿通过本地 MCP 服务连接 AI IDE 并进入代码验收的完整流程图

本地 MCP 的配置入口位于设计文件顶栏；开启后复制服务地址。D2C+ 不再依赖旧版客户端中的独立模式开关，需要时在对话任务中明确使用 D2C+。

启用后不要关闭 Pixso 客户端，也不要关闭包含目标设计对象的文件页签。IDE 能连接本地地址但读取不到设计数据时，这两个状态是第一检查项。

如何连接 Cursor、VS Code、Windsurf、Claude Code 和 Codex？

选定连接路线后，再按客户端要求填写配置。下面示例使用桌面端默认本地地址；远程连接将 URL 改为 https://pixso.cn/mcp 并完成 OAuth 授权，本地端口变化则替换为客户端当前地址。Cursor 和多数客户端使用 mcpServers，VS Code 使用 servers；不要把不同客户端的 JSON 原样混用。

客户端	配置入口	关键格式	成功信号
Cursor	Cursor Settings → MCP & Integrations	`mcpServers` + `url`	服务已启动并显示可用工具
VS Code	Chat → Configure Tools，或 `.vscode/mcp.json`	`servers` + `type: http`	连接状态为 Running
Windsurf	Settings → MCP Servers → Manage MCPs	`mcpServers` + `serverUrl`	刷新后显示 Pixso 服务与工具
Claude Code	终端命令	`--transport http`	服务出现在 MCP 列表
Codex	CLI 或 `config.toml`	`codex mcp add`	`codex mcp list` 可见 Pixso

如果连接后要先确认可读能力，可优先查看工具列表；当前版本中常见的设计读取与转换入口包括 design_to_code、code_to_design、get_node_dsl 和 get_top_level_frames，读取结构可先调用 get_node_dsl；要改设计则先确认写入范围和文件编辑权限。

Cursor 配置示例

打开 Cursor Settings → MCP & Integrations，在 MCP Tools 中新建服务器，或将以下内容写入 Cursor 的 mcp.json：

{
  "mcpServers": {
    "Pixso MCP": {
      "url": "http://127.0.0.1:3667/mcp",
      "headers": {}
    }
  }
}

保存后返回设置页启动 Pixso MCP。只有看到工具列表加载出来，才算完成连接；仅看到配置文件存在并不代表服务可用。

VS Code 配置示例

VS Code 原生 MCP 使用 servers 字段。可以在用户级配置或项目内的 .vscode/mcp.json 中写入：

{
  "servers": {
    "pixso": {
      "url": "http://127.0.0.1:3667/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

保存后刷新 MCP 面板或重新加载窗口，再启动服务器。若界面没有“Configure Tools”或“Add MCP Server”，通常需要升级 VS Code，或确认当前使用的聊天扩展与模型支持 MCP。

Windsurf、Claude Code 与 Codex

Windsurf 可在 Manage MCPs 的原始配置中添加 Pixso 服务。不同版本的字段可能显示为 serverUrl，应以当前配置面板生成的结构为准，本地连接填当前客户端地址，远程连接填 https://pixso.cn/mcp 并授权。

Claude Code 可在终端执行：

claude mcp add --transport http pixso-desktop http://127.0.0.1:3667/mcp

使用 Codex CLI 添加本地服务时，可执行（端口按客户端显示值填写）：

codex mcp add pixso --url http://127.0.0.1:3667/mcp
codex mcp list

MCP 工具是否可见还受文件权限、席位或空间策略和客户端版本影响。写入类智能编辑需要具备相应编辑权限；不要因为配置成功，就默认拥有写入能力。

在 Codex 中添加 Pixso MCP 自定义 HTTP 服务的官方配置界面

怎样在 IDE 中直接打开 Pixso 画布？

Pixso IDE 插件适合“看着稿改设计”的工作方式：在 Cursor、Trae、CodeBuddy 等兼容 IDE 的扩展市场搜索 Pixso，安装后登录账号，再从插件面板选中需要操作的文件。找不到扩展时，可按 Pixso IDE 插件安装说明使用 VSIX 安装。

选定文件之后再下达编辑任务。例如要调整会员资料页的按钮，应先确认画布显示的就是该文件，而不是让 Agent 在上一次打开的页面上操作。插件提供本地 MCP 能力，不是把静态设计截图贴进聊天窗口。

IDE 插件占用 3667 端口时，同时打开的 Pixso 桌面客户端可能改用 3668 或其他可用端口。确认自己要连接哪一端，再把实际地址填入 MCP 配置；不要看到连接失败就盲目在两个端口之间切换。日常只保留一端提供本地服务，更容易定位问题。

如何让 IDE 读取正确的 Pixso 设计稿？

优先复制带 item-id 的“设计层链接”；本地路线也可在画布中单选一个容器。远程任务用有效图层链接定位，不需要保持网页开启；当前选区方式则依赖正在运行的客户端或 IDE 插件及其激活文件。

方式一：复制设计层链接

在 Pixso 中打开设计文件并选中目标 Frame 或容器，远程路线可在网页中复制链接。
复制该设计层的链接。不要只复制文件分享链接或页面链接。
把完整链接粘贴到 IDE 对话中，并说明要生成或检查的具体对象。

方式二：在本地画布中单选容器

保持目标设计文件处于激活页签。
在画布中只选中一个容器，避免同时多选。
在 IDE 中说明“读取 Pixso 当前选中的容器”，再下达任务。

开始写代码前，先让 Agent 返回对象名称、画布尺寸、主要层级、组件和资源清单；在支持的版本中，可先用 get_top_level_frames 获取文件顶层容器，再缩小到目标节点。若它描述的对象不对，立即停止生成并重新定位，避免在错误上下文上继续消耗时间。

第一次调用：先读对对象，再做一次小修改

用一个独立的会员资料卡片开始：它包含头像、姓名、等级和“编辑资料”按钮。先检查读取是否准确，再决定生成代码还是修改设计，避免把接入问题和整页实现问题混在一起。

定位：复制卡片容器的图层链接，检查其中是否有 item-id；文件分享链接和 page-id 不能代替图层 ID。
只读：要求 Agent 读取目标层级，返回对象名称、尺寸、主要文本和子节点。需要进一步分析局部时，再获取更完整的数据。
对照：让 Agent 截取该节点，核对是否为同一张卡片。读到其他页面时停止后续操作，重新确认文件和链接。
小改动：如需编辑设计，先复制一份测试卡片，明确只修改这个副本中的按钮文字，不改主组件、共享样式和其他页面。
回读：修改后再次读取节点并截图，确认只发生了预期变化；需要实现页面时，再进入代码生成和工程验收。

读取这张会员资料卡片的 Pixso 图层链接。先不要修改设计或代码。
返回容器名称、尺寸、主要文本与按钮节点，并截图确认目标。
如果缺少访问权限或节点不存在，请停止，不要猜测设计内容。
确认后，只允许修改我指定的测试副本，不修改主组件与共享变量。

get_node_dsl 用于读取设计结构；take_screenshot 可用于截图检查；apply_design、write_styles、write_variables 等会写入设计文件。工具能列出来，不代表每次调用都具备文件编辑权限。想把团队规范固定下来，可继续配置给 Codex 和 Cursor 使用的设计 Skill；Skill 约束做事方法，MCP 提供设计数据和操作入口，二者并不互相替代。

Pixso MCP 提示词怎么写？

高质量提示词至少包含目标对象、技术栈、复用规则、响应式要求、文件位置和验收标准。“帮我生成代码”只能得到默认答案；把约束写清楚，才能让 Agent 在读取 Pixso 数据后做出更可控的工程决策。

Pixso MCP 提示词的目标对象、技术栈、组件复用、响应式、改动范围和验收标准六项结构

提示词 1：先分析，不改代码

读取这个 Pixso 设计层链接。先不要修改代码。
请返回：1）画布尺寸与页面区域；2）主要图层和组件层级；
3）颜色、字体、间距与圆角；4）图片和图标资源；
5）可能需要复用的现有组件；6）你还缺少的上下文。

提示词 2：生成 React 页面

读取我提供的 Pixso 图层链接所指向的单个容器，并在现有 React + TypeScript 项目中实现。
优先复用 src/components 与现有设计 Token，不新增重复组件。
布局优先使用 Flex/Grid，不用绝对定位复刻整页。
补齐桌面、平板和移动端状态，保留现有路由与数据接口。
完成后运行项目检查，并列出修改文件、未能确认的设计细节和验收步骤。

提示词 3：只修复视觉差异

比较当前实现与这个 Pixso 设计层。不要重写业务逻辑。
按影响排序列出差异：布局、尺寸、间距、字体、颜色、圆角、阴影、资源和响应式。
先给出修复计划，再只修改相关样式与展示组件。
完成后说明每一处差异的修复位置，以及仍需人工确认的内容。

提示词 4：生成可复用组件

读取该 Pixso 组件及其状态，生成可复用的 Vue 3 + TypeScript 组件。
把尺寸、颜色和间距映射到项目现有变量；将状态设计为明确的 props；
覆盖默认、悬停、禁用、加载和错误状态；补充使用示例。
不要把示例文案硬编码为业务数据，也不要创建第二套设计 Token。

如果团队已经建立Pixso 设计系统，应在提示词中明确“优先复用组件、变量和 Token”。这比单纯要求“像素级还原”更利于后续维护。

生成代码前如何整理 Pixso 设计稿？

结构清楚的设计稿比更长的提示词更有效。图层层级过深、遮罩过多、同名对象密集或把多个页面塞进一个超大容器，都可能增加上下文体积并降低模型判断质量。

缩小范围：按页面区域或组件分批读取，不要一次提交整个大型文件。
语义命名：使用 Header、ProductCard、EmptyState 等可理解名称，避免大量“Frame 123”。
复用组件：将重复 UI 建成组件及变体，并用变量管理颜色、字体、间距和圆角。
补齐状态：给表单、列表、弹窗准备加载、空、错误、禁用和移动端状态。
清理无关内容：删除废弃图层，压平不需要继续编辑的复杂装饰，确认图片资源可访问。
控制返回体积：大型文件先按 Frame 或页面区域拆分，避免让一次调用承载过多图层、图片和文本。

Pixso MCP 常见问题怎么排查？

先分清连接路线，再查服务或授权、目标对象、文件权限，最后检查生成结果。远程接入先看 OAuth 是否完成；本地接入先看客户端或插件是否运行。下图用于本地连接，远程服务不需要从“打开客户端”开始。

IDE 显示连接失败

常见原因：本地 MCP 未启用或端口错配、远程 OAuth 未完成、JSON 字段错误，或 IDE 不支持当前传输方式。

处理与验证：本地连接复制客户端实际服务地址；插件与桌面端同时运行时检查端口。远程连接检查 https://pixso.cn/mcp 与授权状态。MCP 面板能列出工具后，还要做一次目标图层读取，才能确认任务所需访问已通。

已连接但读取不到设计稿

常见原因：本地路线的客户端或设计文件已关闭、目标页签不活跃；远程路线可能授权账号不对，或使用了不带图层 ID 的分享链接。

处理与验证：本地路线保持服务运行并激活目标页签；远程路线检查 OAuth 账号和文件可查看权限。重新复制带 item-id 的链接，让 Agent 返回对象名称、尺寸和层级，确认与目标一致。

读到了错误页面或对象

常见原因：链接没有指向目标设计层、画布中同时多选，或切换页签后仍沿用旧上下文。

处理与验证：重新单选一个容器并复制新链接，新开对话或让 Agent 重新读取。生成前的对象摘要应与目标 Frame 一致。

工具调用超时或内容截断

常见原因：容器过大、图层和遮罩太多、资源复杂，或上下文接近模型上限。

处理与验证：按区域拆分任务、清理无关图层，先分析再分批生成；先用 get_node_dsl 或对象摘要确认范围，再进入代码生成。小容器能够稳定读取且返回内容完整，说明拆分有效。

页面能运行但还原度低

常见原因：提示词缺少框架和设计约束、设计稿没有状态或 Token，或当前模型难以处理复杂页面。

处理与验证：补充技术栈、复用规则和验收项，先生成结构，再逐项修复视觉差异。关键尺寸、字体、资源和断点都应通过对照检查。

生成了重复组件或硬编码样式

常见原因：Agent 没有先读取现有代码库，提示词也没有要求复用组件与变量。

处理与验证：先让 Agent 搜索组件目录和 Token，再限制新增文件与硬编码值。最终代码应引用现有组件和变量，并移除重复实现。

图片或图标缺失

常见原因：资源未导出、链接不可访问，或目标容器没有包含对应资源上下文。

处理与验证：让 Agent 先列出资源清单，确认图片可访问，必要时单独处理资源节点。本地预览不应出现 404，图片比例与裁切也应正确。

工具不可见或写入被拒绝

常见原因：客户端版本、文件权限、席位或空间策略限制了工具范围；读取能力正常，也不代表当前会话具备写入权限。

处理与验证：先查看工具列表和当前文件权限，确认使用的是支持当前 MCP 版本的客户端；需要修改设计时，确认账号具有编辑权限。设计转代码还要检查企业席位及文件是否位于企业空间。若出现额度提示，核对提示中的限制类型；不要把旧版本的调用次数当作所有账号的统一权益。

仍无法连接时，可用另一个支持 Streamable HTTP 的客户端测试同一路线。远程服务同时失败应检查网络与授权，本地服务同时失败应检查运行状态和端口。已经能连接但读取内容错误，可按Codex 读取设计稿失败的检查步骤核对工具返回值与节点层级。

如何验收 Pixso MCP 生成的代码？

MCP 提供设计上下文，不替代工程验收。至少检查结构复用、视觉还原、响应式、交互状态、可访问性、性能和构建结果。不要只在一个桌面宽度下对比截图。

先跑通：安装依赖、启动项目并通过类型检查、Lint 与构建。
再对照：检查主要容器尺寸、间距、字体、颜色、圆角、阴影、图片裁切和图标。
测断点：至少覆盖桌面、平板和移动端，确认没有横向溢出、遮挡或文字截断。
测状态：检查加载、空、错误、禁用、悬停、聚焦和表单校验。
审代码：确认没有整页绝对定位、重复组件、散落的魔法数字和无关文件改动。
验工具结果：确认 design_to_code、get_node_dsl 等读取结果与目标对象一致；写入类操作前再次确认编辑权限。

如果要建立团队级验收标准，可参考D2C 代码质量评测方法，把“能生成”拆成结构质量、视觉一致性、可维护性和多端适配等可验证指标。

Pixso MCP 常见问题

Pixso MCP 可以在浏览器版 Pixso 中直接使用吗？

可以从网页复制图层链接，交给已授权的远程 MCP 使用；完成授权且链接有效时，不必保持 Pixso 网页开启。本地 MCP 则仍需要桌面客户端或 IDE 插件保持运行，两种方式不要混用前提。

Cursor 已连接 Pixso MCP，为什么还提示没有设计数据？

先检查路线：本地接入核对激活文件与选区；远程接入核对授权账号、文件权限及链接中的 item-id。让 Cursor 返回对象名称与尺寸，确认定位正确后再生成代码。

Pixso MCP 能一次读取多个容器吗？

使用画布选中方式时应一次选择一个容器。多个页面建议按区域拆分，分别读取和生成，再由 Agent 在代码层组合。

为什么同一份 Pixso 设计稿生成结果不同？

结果会受所选范围、提示词、代码库上下文、目标框架、模型能力与上下文长度影响。固定设计层链接、模型、提示词模板和验收清单，能减少不必要的波动。

Pixso MCP 可以直接生成 React、Vue 或小程序代码吗？

可以通过 design_to_code 生成 React、Vue 等代码，当前工具说明还列有 HTML、ArkUI 和 Flutter。小程序不是这些框架的同义词，不能把已有输出直接当作小程序工程；需要另外处理目标组件、样式、资源与运行时，并完成实际运行检查。

连接成功后，是否还需要设计标注和人工评审？

仍然需要。MCP 能减少手工读取设计信息的工作，但业务逻辑、响应式决策、无障碍、性能、安全和代码维护仍应由团队验收。

为什么连接成功后看不到全部 MCP 工具？

工具范围可能受客户端版本、文件权限、席位或空间策略影响。先刷新工具列表，再检查当前账号的席位、目标文件可查看或可编辑权限；只有本地路线需要继续检查客户端和激活文件。

Pixso MCP 是否有调用次数限制？

是否可调用，首先取决于席位、目标文件权限及对应能力；遇到限制时，应区分权限不足、调用额度与模型服务限制。账号中的用量提示是排查入口，不能用旧版每日次数替代当前席位条件。

Paico 和 Pixso MCP 分别适合什么阶段？

Paico 适合从一句需求出发探索方案、比较方向并快速生成可交互原型；Pixso 负责专业设计协作、设计系统和工程交付，MCP 则把 Pixso 的设计上下文传给 IDE 与代码仓库。两者是前后衔接的工作流，而不是相互替代。

Pixso MCP教程：连接Codex与Cursor