Claude Code接入Pixso MCP教程

Claude Code 接入 Pixso MCP，可以先在前端项目目录执行 claude mcp add --transport http pixso-oauth-mcp https://pixso.cn/mcp，再在 Claude Code 中用 /mcp 完成授权。接着提供带 item-id 的 Pixso 图层链接，让它读取设计结构与现有组件，最后分步实现页面、检查交互，不要一上来就要求“整站一比一还原”。

这条工作流适合已经有设计稿和代码仓库的团队。Pixso MCP负责连接真实设计对象，Claude Code 负责结合仓库完成实现。下面以一个 React＋TypeScript 项目的团队成员邀请页为例，把邮箱输入、角色选择、邀请反馈和成员列表接起来。

连接前，先分清三件事

远程MCP和本地MCP，选一条主线

远程服务运行在 Pixso 云端，公网地址是 https://pixso.cn/mcp，通过 OAuth 授权后访问你有权限的文件，不要求一直打开 Pixso 网页。它适合拿到明确图层链接，再回到终端推进代码任务。私有化环境应使用企业自己的服务地址，不要直接套用公网地址。

本地服务由 Pixso 客户端或 IDE 插件提供，适合围绕当前打开的文件和选区操作。Pixso 客户端需要 2.2.0 或以上版本；通常显示为 http://127.0.0.1:3667/mcp，但端口可能变化，要以客户端当前显示的地址为准。使用期间保持客户端开启、已登录，目标文件页签处于激活状态。

本地Pixso MCP也是HTTP服务，不是stdio，也不支持SSE。不要因为服务在自己的电脑上，就照着其他工具的教程添加 npx 启动命令。下面先使用远程 OAuth；需要本地连接时，再替换服务地址。

授权连接，不等于拥有全部文件和能力

Pixso MCP 需要全功能席位或研发席位。读取目标设计文件需要查看权限，修改画布还需要编辑权限。OAuth 只完成身份授权，不会把只读文件变成可编辑文件。

也要分清两种代码工作流：一种是 Claude Code 读取设计数据后，结合现有项目编写代码；另一种是调用 Pixso 的 design_to_code 等 D2C+ 能力。后者需要企业版对应席位，目标文件也须位于企业空间。普通 MCP 连接不能代替这些条件。

准备一个小而完整的页面

练习页面只承担一项任务：管理员填写邮箱、选择角色，邀请成员加入团队。页面包含一组邀请表单，以及显示邮箱、角色、邀请状态的列表。先不加入部门管理、批量导入和审批流，避免首次接入就让多个业务问题混在一起。

设计稿至少要能看出默认状态、提交中、重复邀请和成功反馈。代码仓库则准备好现有的输入框、选择器、按钮、表格和提示组件。先保存当前工作版本，再让 Claude Code 读取项目；不要让它用一份独立 HTML 覆盖已经存在的 React 页面。

用OAuth连接Pixso远程MCP

1. 在目标项目目录添加服务

打开已能正常使用 Claude Code 的终端，进入要实现页面的项目目录。先确认 CLI 可用，再添加 Pixso：

claude --version
claude mcp add --transport http pixso-oauth-mcp https://pixso.cn/mcp
claude mcp list
claude mcp get pixso-oauth-mcp

Added 只代表配置已经写入。看到需要认证时，启动 Claude Code，在对话中输入：

/mcp

选择 pixso-oauth-mcp，按提示在浏览器中登录并完成授权，再回到 Claude Code 查看连接状态。配置成功、服务已连接、读到正确设计图层是三个不同结果，需要依次确认。

2. 配置为什么换个项目就不见了？

不指定作用域时，Claude Code 默认使用 local：配置仅对当前项目、当前用户生效。这里的 local 是“配置可用范围”，不是说 Pixso 服务运行在本机。

如果团队选择手动维护 .mcp.json，Claude Code 的 HTTP 服务项要显式写出 type：

{
  "mcpServers": {
    "pixso-oauth-mcp": {
      "type": "http",
      "url": "https://pixso.cn/mcp"
    }
  }
}

不要把别的客户端配置路径直接搬过来，也不要把个人访问令牌提交到仓库。首次使用共享项目配置时，先检查服务地址，再处理 Claude Code 的审批提示。无需为了教程方便关闭权限确认。

3. 需要本地连接时怎么改？

先在 Pixso 客户端开启 MCP，复制当前显示的本地地址，然后使用一个不同的服务名称。以下命令适用于客户端确实显示 3667 端口的情况：

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

不要同时让多个 Pixso 客户端或插件争用同一个端口。若连接突然中断，先看客户端是否关闭、端口是否变化，以及设计文件是否切换到了非激活页签。

第一轮：读对图层，不急着写代码

复制容器链接，而不是整个文件的分享地址

在 Pixso 打开成员邀请页，选中包含表单与成员列表的业务容器，右键复制图层链接。链接中的 item-id 用来定位图层；文件分享链接和页面的 page-id 不能替代它。

容器也不宜过大。整套后台可能包含多个页面、隐藏图层和无关素材，第一次只读成员邀请区域更容易确认“读的是不是这张稿”。若表单和列表位于不同容器，分别给出链接，并说明它们属于同一页面。

先给 Claude Code 一轮只读任务：

读取这个 Pixso 团队成员邀请页的图层链接，只分析，不修改画布和仓库。确认邮箱输入、角色选择、邀请按钮、反馈信息和成员列表的结构。再读取当前 React＋TypeScript 项目的组件目录，找出可复用的输入框、选择器、按钮、表格和提示组件。先列出组件对应关系、缺失状态以及预计修改的文件，不要猜测没有读到的组件属性和接口。

这一轮应该得到具体对象，而不是“页面简洁、布局合理”之类评价。例如，设计中的角色下拉框能否对应项目的 Select，按钮有没有 loading 状态，列表的状态标签是否已有组件。无法确定时，让它继续读相关文件，不要默认所有组件都使用同一套 API。

当前 Pixso 工具文档提供 get_node_dsl 读取结构，read_components、read_styles 和 read_variables 读取设计资源；远程截图可使用 take_screenshot。让 Agent 根据当前可用工具完成这些动作，不要硬写旧工具名，也不要把“截图上相似”当成已正确读取组件。

设计组件和代码组件不是同一个对象

设计稿中的一个“主要按钮”可能拥有颜色、圆角和状态变体，代码里的 Button 还包含事件、禁用、加载、无障碍属性等约定。MCP 让这些信息更容易被读取，但不会自动证明二者完全一一对应。

可以要求 Claude Code 输出一份短映射，例如“邀请按钮 → 项目 Button 的 primary 变体；提交中 → 已有 loading 属性；禁用 → 请求未结束或当前用户无邀请权限”。如果仓库组件没有某项能力，先确认是组合现有组件还是扩展组件，不另造一套同名控件。

第二轮：约定邀请数据与状态

只给设计稿，AI 常能写出表单外观，却不知道“邀请成功”之后列表该出现什么。本例把邀请结果定义为一条待接受的邀请，而不是立即成为已加入的成员。练习使用下面的数据约定，它属于这个业务页面，不是 Pixso API：

type TeamRole = 'editor' | 'viewer';
type InvitationStatus = 'pending' | 'accepted';

type InviteMemberInput = {
  email: string;
  role: TeamRole;
};

type MemberInvitation = {
  id: string;
  email: string;
  role: TeamRole;
  status: InvitationStatus;
};

type InviteMemberResult =
  | { ok: true; invitation: MemberInvitation }
  | {
      ok: false;
      code: 'DUPLICATE_EMAIL' | 'FORBIDDEN' | 'NETWORK_ERROR';
      message: string;
    };

type InviteMember = (
  input: InviteMemberInput
) => Promise<InviteMemberResult>;

把调用隔离为 inviteMember 适配函数，页面只处理结果。练习阶段可以接本地模拟实现，后续替换真实接口时，不必重写整张页面。不要让 AI 自行编造后端路由、邮件服务或数据库表，再把它们当作现有能力。

前端校验的作用是及时反馈，重复邮箱和邀请权限仍要由服务端判断。邮箱是否统一小写、哪些角色允许被邀请，也应沿用实际业务规则，不能只凭 UI 文案决定。

可以把第二轮任务限定为：

沿用刚才确认的组件映射，实现成员邀请表单和列表状态。接口暂时通过独立的 inviteMember 适配函数注入，返回值使用给定的 TypeScript 类型。准备正常邀请、重复邮箱、网络失败和无权限四种模拟结果，分别可切换验证。成功后加入返回的待接受记录；失败保留输入；不要接真实邮件发送，不修改登录和权限系统。

第三轮：接进现有React项目

先看仓库约定，再决定放在哪个文件

Claude Code 的优势不只是生成一段 JSX，而是能够结合仓库继续做事。让它先读取 package.json、已有页面路由、表单用法和一处类似列表，再给出最小修改方案。项目使用 CSS Modules、Tailwind 还是其他样式方案，应沿用已有约定，不在一个页面里混入新的整套技术栈。

如果项目已有成员页面，直接在该页面补充邀请区域；如果还没有，再增加对应路由。不要因为设计稿有侧边栏，就复制一份全新的应用外壳，让页面同时出现两套导航。

把成员邀请功能接入当前项目已有的团队设置页面。复用现有应用布局、表单组件和反馈组件，只修改完成本任务所需的文件。颜色和间距优先映射到项目已有token；缺少对应值时列出差异，不把所有数值硬编码在组件里。完成后列出修改文件、需要补接的真实接口，以及实际运行过的检查命令和结果。

状态应围绕一次提交组织

至少区分空闲、提交中、成功和失败。发起请求前保存本次表单值，提交未结束时防止同一操作被反复触发；请求返回后，再决定清空邮箱、显示错误或更新列表。

页面代码应处理成功结果与已知错误，也要处理适配函数意外抛出的异常。只写“成功就弹提示”容易漏掉超时、断网或响应解析失败。可以让 Claude Code检查失败路径是否都回到可操作状态，避免按钮一直转圈。

成功后更新列表时，以返回记录的 id 作为稳定标识。若项目使用查询缓存，应沿用已有刷新或缓存更新方式；没有对应机制时，再采用局部状态更新。不要同时追加本地记录又无条件追加接口刷新结果，导致同一邀请显示两次。

需要D2C+时，仍要接上工程规则

具备企业 D2C+ 条件的团队，可以让 Agent 使用 design_to_code 生成 React 代码，再对齐当前项目的组件规范。它能提供界面代码起点，但角色权限、重复邀请判定、服务异常和真实数据接入仍需按业务完成。

没有调用这项能力时，应明确要求 Claude Code 基于已读取的设计结构实现当前项目，不要让它把 MCP 读取动作描述为 D2C+ 已执行。无论选择哪条路径，验收对象都是同一个成员邀请流程。

第四轮：核对设计与交互

先把页面跑起来，再逐项对照

让 Claude Code 读取项目实际配置的检查脚本，执行已有的类型检查、lint、测试和构建。项目没有某个脚本时，应说明缺项或使用已存在的替代命令，不要凭空报告“全部通过”。终端没有报错，也不能替代浏览器中的阅读和点击检查。

打开开发页面，与 Pixso 的同一容器比较：标题层级、表单宽度、标签与输入框间距、角色说明、按钮状态、错误信息位置、列表列宽。每次只修一组明确差异，避免一句“再高级一点”把已经正确的结构一起改掉。

可使用下面这组最小检查，输入全部采用练习数据：

1. 邮箱留空提交：焦点与错误提示指向邮箱字段，不产生新列表行。
2. 填写 lin@example.test 并选择查看者：提交期间按钮不能重复触发；返回成功后出现“待接受”记录。
3. 再次邀请同一邮箱：出现重复提示，列表仍只有一条对应记录。
4. 切换到网络失败结果：邮箱和角色保留，按钮恢复可操作，用户能重试。
5. 切换到无权限结果：不能靠重新启用按钮绕过拒绝；界面清楚说明操作不可用。
6. 缩窄窗口并用键盘操作：标签没有被截断，焦点顺序合理，角色下拉框、按钮和反馈都能理解。

这里要特别看一处语义：“已发送邀请”不等于“成员已加入”。如果列表显示“已加入”，但收件人还没有接受，视觉还原再好也是业务错误。通过状态契约把这种差别提前交给 Agent，往往比后期反复改文案更有效。

修改收敛到具体差异

只修复这三处：错误提示应紧贴邮箱字段；提交失败后保留当前角色；成功记录的状态显示为“待接受”。不要改动页面布局、导航和其他字段。修改后分别验证重复邮箱与网络失败路径，并对照Pixso检查提示位置。

如果设计团队希望把代码中的新状态补回 Pixso，单独提出画布修改任务，明确目标文件和新增区域，先保留原稿。代码实现完成并不自动授权 Agent 改写设计系统或批量替换其他页面。

项目有长期 UI 规则时，可以用 Skill 或项目说明保存组件选择、命名和检查流程；MCP 提供当下可读取的设计对象。规则不会自动带来文件权限，连接也不会自动替你决定正确的业务行为。两者配合，才能减少每次重新解释同一套约定。

连接和实现失败，分别怎么排查

需要移除默认 local 作用域下的旧配置时，可以执行 claude mcp remove pixso-oauth-mcp --scope local。不要清空全部 MCP 设置来解决一个服务问题。如果改用 Pixso 个人访问令牌，官方 CLI 示例使用的是 --header "Token:个人访问令牌"，而不是其他服务常见的 Authorization 头；优先保留 OAuth，避免把密钥放进命令截图和仓库。

成员邀请页完成后，再把相同方法扩展到其他业务容器：每次明确图层、组件、数据和失败状态，先得到一个可运行、可检查的小闭环。Pixso 中保留可编辑的设计依据，Claude Code 中沿用真实项目约定，设计调整与工程修改才容易持续衔接。