capacitor-mcp

Capacitor MCP 服务

将 MCP 服务接入 Agent，使其能够读取 Ionic/Capacitor 文档、运行 Capacitor CLI 命令、管理 Capgo 并操作 Xcode。

适用场景

当用户出现以下情况时触发：

• 要求“添加 MCP 服务”／“将 Claude/Cursor 连接到 Capacitor、Ionic、Capgo 或 Xcode”
• 提及 awesome-ionic-mcp、api.capgo.app/mcp、@capgo/cli mcp、xcrun mcpbridge、claude mcp add、.cursor/mcp.json、.vscode/mcp.json、claude_desktop_config.json
• MCP 服务无法启动、未显示工具、要求登录或触及速率限制

以下情况不要使用：

• 作为任务上传 bundle、管理 channel 或 rollout、执行原生构建：使用 capgo-cloud、capgo-cli-usage、capgo-live-updates、capgo-native-builds
• 查找或安装插件：使用 capacitor-plugins
• 运行时错误和崩溃：使用 debugging-capacitor；设备日志：使用 ios-android-logs
• Ionic 组件设计和主题设置：使用 ionic-design

选择服务

需求	服务	传输方式
Ionic 组件 API／演示、Capacitor 插件文档、运行 ionic／cap 命令	awesome-ionic-mcp（社区项目，npm）	通过 npx 使用 stdio
Capgo 账户：应用、bundle、channel、rollout、设备、统计数据、构建状态／日志、webhook、推送	Capgo 托管 MCP https://api.capgo.app/mcp	可流式传输的 HTTP、OAuth 或 API key
从 dist/ 上传 bundle、请求原生构建、运行 doctor、probe、兼容性检查	Capgo 本地 CLI MCP npx @capgo/cli@latest mcp	stdio
构建／运行 iOS 项目、读取 Xcode 问题、使用 Xcode 工具	Xcode MCP xcrun mcpbridge（Xcode 26.3+，已在 Xcode 27.1 上验证）	stdio

Capgo 托管服务和本地服务互为补充：托管服务无法读取本地文件；本地服务需要先运行 npx @capgo/cli@latest login。两者的设置指南：https://capgo.app/mcp

操作步骤

1. 先检查：确认客户端（Claude Code、Claude Desktop、Cursor、VS Code、Cline、Codex），并在编辑前读取其现有 MCP 配置。不要覆盖其他服务。

2. 选择范围：当团队需要共享配置时，使用项目配置（.cursor/mcp.json、.vscode/mcp.json、claude mcp add --scope project）；否则使用用户／全局配置。如不确定，询问用户。

3. 添加服务。Claude Code 单行命令：

   claude mcp add --transport stdio awesome-ionic-mcp -- npx -y awesome-ionic-mcp@latest
   claude mcp add --transport http capgo https://api.capgo.app/mcp
   claude mcp add --transport stdio capgo-cli -- npx @capgo/cli@latest mcp
   claude mcp add --transport stdio xcode -- xcrun mcpbridge
   

   其他客户端：加载下方对应的参考内容。

4. 验证身份：

   • Capgo 托管服务：在 Claude Code 中运行 /mcp，选择 capgo 并登录（OAuth 2.1）。不支持 OAuth 的客户端需发送 Authorization: Bearer <Capgo API key>。
   • Capgo 本地服务：在此计算机上运行一次 npx @capgo/cli@latest login。
   • Xcode：在 Xcode Settings > Intelligence 中启用外部 Agent，保持项目打开，并在 Xcode 提示中批准 Agent。
   • awesome-ionic-mcp：可选设置 GITHUB_TOKEN 环境变量，用于获取插件目录。

5. 重启或重新加载客户端，然后运行验证。

陷阱

• 密钥：如果用户已在配置中设置了 GITHUB_TOKEN 或 Capgo API 密钥，请保持原样。使用 Capgo 托管服务时优先选择 OAuth；使用权限范围最小的密钥（报告场景使用只读权限）。切勿将密钥提交到项目级配置中；请使用环境变量或用户级配置。
• Capgo 托管工具包含有破坏性的操作（删除应用、设置通道 bundle、回滚）。客户端会请求确认；不要自动批准。
• OAuth 会话会创建一个名为 MCP · <client name> 的密钥，最长 90 天后过期。过期后通过 /mcp 重新连接；如需撤销，请在控制台中删除该密钥。
• awesome-ionic-mcp 会在 project_directory 中运行 ionic/npx 命令（默认为最近的项目根目录，其次为当前工作目录）。仅允许使用 ionic、@ionic/cli、@capacitor/cli 和 cap* 包；包含 ; & | $ ( ) { } [ ] < > 的参数会被拒绝。
• ionic_serve 和 capacitor_run 会阻塞，或需要连接设备；最好在用户掌控的终端中运行。
• awesome-ionic-mcp 的参数为 html_tag（而非 tag）、Capgo/社区插件使用 repo_name、官方插件使用 plugin_name、第三方目录使用 slug。先调用 get_all_* 工具以获取准确名称。
• xcrun mcpbridge 通过 xcode-select 查找 Xcode。如果当前的开发者目录是 /Library/Developer/CommandLineTools，则无法找到它。
• Xcode 会按进程进行审批：重启 Agent 会触发新的审批提示。
• 未启用 Intelligence 设置时，xcrun mcpbridge 可以连接，但不会提供任何工具。

验证

claude mcp list                  # each server shows connected / needs auth
claude mcp get capgo             # shows transport and URL
xcrun --find mcpbridge           # Xcode bridge resolvable
xcrun mcpbridge run-agent --dry-run claude   # prints the resolved Claude command with Xcode config

然后对每个服务进行一次只读工具调用，并确认返回了实际结果：

• awesome-ionic-mcp：使用 html_tag: "ion-button" 调用 get_ionic_component_definition，或调用 get_all_capgo_plugins
• Capgo 托管服务：“列出我的 Capgo 应用”
• Capgo 本地服务：调用 capgo_list_apps 或 capgo_doctor
• Xcode：让 Agent 构建 iOS 应用（在 Xcode 中打开 ios/App/App.xcodeproj 或 App.xcworkspace）

在 Cursor/VS Code/Claude Desktop 中，检查 MCP 面板，确认服务已启用且工具数量大于零。

错误处理

错误 / 症状	解决方法
GitHub API rate limit exceeded. Set GITHUB_TOKEN environment variable to increase limits.	将 GITHUB_TOKEN（访问公共仓库无需任何权限范围）添加到服务的 env 中，然后重启。
Plugin not found: <name>（awesome-ionic-mcp）	使用对应 get_all_* 工具返回的准确 repo_name/slug。
Component not found: <tag>	传入真实的 Ionic 标签，例如 ion-modal；使用 get_all_ionic_components 列出标签。
Command '<cmd>' is not allowed / NPX package '<pkg>' is not allowed / Argument contains dangerous characters	该服务只会使用普通参数运行 Ionic/Capacitor CLI；其他命令请在终端中运行。
Failed to download core JSON data from Ionic.	启动时发生网络问题；请检查网络连接/代理，然后重启服务。
xcrun: error: unable to find utility "mcpbridge", not a developer tool or in PATH	运行 sudo xcode-select -s /Applications/Xcode.app/Contents/Developer，或将 Xcode 更新到 26.3+。
Xcode 服务已连接，但工具数量为零	在 Xcode Settings > Intelligence 中启用外部 Agent，并打开项目。
Capgo 托管服务显示“needs authentication”	运行 /mcp（Claude Code），或点击客户端的登录提示；90 天密钥过期后重新连接。
Capgo 本地工具因身份验证错误而失败	在该机器上运行 npx @capgo/cli@latest login。
服务在 Claude Desktop 中启动后立即退出	Node/npx 不在图形界面的 PATH 中；在 command 中使用 npx 的绝对路径。

参考资料

仅在涉及相关主题时加载参考资料。

• references/awesome-ionic-mcp.md：客户端配置（Claude Desktop、Cursor、Cline、VS Code）、包含已验证参数的完整工具列表、实时查看器。
• references/capgo-mcp.md：托管式与本地 Capgo MCP、各客户端的设置（Claude.ai、ChatGPT、Cursor、VS Code、Lovable、API 密钥标头）、工具覆盖范围。
• references/xcode-mcp.md：面向 Claude Code 和 Codex 的 Xcode MCP 桥接设置、run-agent、无头 mcp-server 命令、Capacitor iOS 工作流。

资源

• awesome-ionic-mcp：https://github.com/Tommertom/awesome-ionic-mcp
• Capgo 托管式 MCP：https://capgo.app/docs/ai/mcp/
• Capgo CLI MCP：https://capgo.app/docs/cli/reference/mcp/
• Xcode 外部 Agent：https://developer.apple.com/documentation/xcode/giving-external-agents-access-to-xcode
• Claude Code MCP：https://docs.anthropic.com/en/docs/claude-code/mcp
• MCP 规范：https://modelcontextprotocol.io