Gemini Design MCP 是把 Gemini 前端生成能力接入 AI 编辑器或 Agent 的第三方工具。它和 Google 官方的 Gemini Canvas、Stitch 不是同一个产品。配置时要分别确认客户端、MCP 服务和密钥，再用一个小界面验证连接与文件修改。本文依据产品方及客户端文档整理操作方法，示例是练习方案，不是已在你的环境中运行过的实测记录。还不确定该选哪条路径，可先看Gemini Design 中文指南。
1. 安装前准备：先看密钥、目录与权限
准备一个支持 MCP 的客户端，例如 Claude Code；本地运行方式还需要客户端能找到 Node.js 和 npx。产品文档标注的最低 Node.js 版本为 18，实际应选仍受支持且与当前工具兼容的版本。
随后确认密钥来源：平台账户的 API Key 与你在 Google AI Studio 创建的 Google API Key，不应只因名字相近就互换。产品主页提供两种接入选项，按你选择的方式复制对应配置。先建一个只含演示文件的练习项目，不连接真实客户数据库，并留下一份可恢复的代码版本。普通文件夹本身不是权限隔离工具；还要在客户端设置中检查工具能访问哪些目录、是否可自动写文件。
这些准备工作的目的，是把第一次运行的影响控制在你能读懂的范围内。完整项目里只需改一张卡片时，也没有必要把账号凭证、支付配置和整份后端代码作为设计上下文发出去。
2. 本地与远程接入怎么选
本地模式由客户端启动 MCP 进程，适合已经配置 Node.js、希望管理工具版本的环境；远程模式连接服务方托管的地址，配置重点变为服务地址、认证方式和客户端支持的连接类型。以产品方当前配置面板为准，不把旧教程里的地址与新教程的认证字段拼在一起。
“MCP 在本地运行”不等于“Gemini 在本地推理”。涉及云端模型的请求仍需要网络，也可能发送本次任务所需的界面上下文。连接方式改变的是服务如何运行，不能据此推断数据绝不出设备。MCP 的本地与远程机制可参阅协议架构说明。
3. 添加配置并检查连接状态
下面是产品方提供的 Claude Code 本地配置形式。YOUR_API_KEY 是占位符，不是真实密钥；@latest 会使用当时最新包。正式项目建议先验证一个具体版本，再按包版本写法替换 latest，避免后续启动时不知不觉改变工具行为。
claude mcp add gemini-design-mcp --env API_KEY=YOUR_API_KEY -- npx -y gemini-design-mcp@latest真实密钥优先通过客户端支持的秘密存储或环境变量机制提供；不要把含密钥的命令、配置截图或终端历史公开，也不要提交到代码仓库。Google 自有密钥的配置规则应另外核对Google API Key 文档。
添加后，打开 Claude Code 的 /mcp 面板，或执行 claude mcp list 查看状态。“配置已添加”只说明记录写入，不能代替连接验证。其他客户端请在各自的 MCP 设置里检查；不要把 Claude Code 的命令原样当成 Cursor 的配置。配置步骤来源：Gemini Design MCP 文档、Claude Code MCP 文档。
4. 用一个最小页面验证，不急着生成整站
第一次只做课程预约卡片，既能判断结果是否可用，也方便找出连接、提示词和界面本身的问题。新建页面可使用 create_frontend；调整已有部分对应 modify_frontend；补充独立组件可看 snippet_frontend。以客户端实际发现的工具为准。
在当前练习项目中新建课程预约卡片。使用项目已有技术栈，展示课程名、时长、讲师和预约按钮；数据全部虚构。桌面单行排列，手机竖向排列。只修改指定演示文件，不增加登录、支付或外部接口。先说明要修改的路径，再生成。
拿到结果后，检查四件事：文件是否写到了预期位置；项目能否启动；按钮是否有明确的行为或演示说明；390px 宽度下文字和按钮是否完整。再要求“只调整课程信息间距，保留已有字段和按钮行为”，观察局部修改是否扩大成整页重写。需要更多场景，可使用Gemini Design 中文提示词模板。
5. 连接失败、没有工具或输出不对怎么排查
- 进程无法启动：先确认客户端能找到 Node.js/npx，再看包下载、版本与启动日志。终端能运行，不代表桌面客户端继承了相同环境。
- 认证失败：检查密钥类型、失效状态、前后空格及账户权限；不要在群聊里粘贴完整配置求助。
- 连接了但没有工具：检查是否选中正确项目与配置范围，重新连接并确认工具清单，再执行最小练习。
- 超时或额度不足：先查看服务状态与用量记录，缩小输入范围；连续重试可能继续消耗额度。
- 生成后破坏原页面：查看代码差异并恢复不相关改动，补充原有样式、字段与交互约束，再进行小范围修改。
6. 控制成本，并把结果带入设计评审
使用前记录计费方、当前额度与本次调用消耗。2026年9月13日核验时，服务主页和文档的免费额度表述并不一致，因此不宜用某个固定数字估算可生成多少页面；以账户当前显示的权益和账单为准。采用自有 Google Key 时，还要查看对应 Google 项目的用量。
生成代码之后，下一步是验证设计是否适合产品：字段完整吗，空状态怎么显示，手机端的信息顺序合理吗？可以将截图和需求放入 Pixso UI 设计协作流程评审，并按确定的颜色、间距和组件规则整理设计稿；代码不会因为放进截图而自动变成可编辑图层。希望比较 Canvas 和 Stitch 的设计路径，可继续看Gemini Canvas 与 Stitch 工作流。已有明确需求时，也可以进入 Pixso 工作台，从可持续修改的页面方案开始。
