Capacitor MCP Servers

Wire MCP servers into an agent so it can read Ionic/Capacitor docs, run Capacitor CLI commands, manage Capgo, and drive Xcode.

When to Use

TRIGGER when the user:

• asks to "add an MCP server" / "connect Claude/Cursor to Capacitor, Ionic, Capgo or Xcode"
• mentions 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
• has an MCP server that fails to start, shows no tools, asks to sign in, or hits a rate limit

Do not use for:

• uploading bundles, channels, rollouts, native builds as a task: capgo-cloud, capgo-cli-usage, capgo-live-updates, capgo-native-builds
• finding or installing a plugin: capacitor-plugins
• runtime bugs and crashes: debugging-capacitor; device logs: ios-android-logs
• Ionic component design and theming: ionic-design

Pick the Server

The Capgo hosted and local servers are complementary: hosted cannot read local files; local needs npx @capgo/cli@latest login first. Setup guide for both: https://capgo.app/mcp

Procedure

1. Inspect first: identify the client (Claude Code, Claude Desktop, Cursor, VS Code, Cline, Codex) and read its existing MCP config before editing. Do not overwrite other servers.
2. Choose scope: project config (.cursor/mcp.json, .vscode/mcp.json, claude mcp add --scope project) when the team should share it; user/global config otherwise. Ask the user if unclear.

3. Add the server. Claude Code one-liners:

   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

   Other clients: load the matching reference below.

4. Authenticate:
   • Capgo hosted: run /mcp in Claude Code and pick capgo to sign in (OAuth 2.1). Clients without OAuth send Authorization: Bearer <Capgo API key>.
   • Capgo local: npx @capgo/cli@latest login once on the machine.
   • Xcode: enable external agents in Xcode Settings > Intelligence, keep the project open, approve the agent in Xcode's prompt.
   • awesome-ionic-mcp: optional GITHUB_TOKEN env var for plugin catalog fetches.
5. Restart or reload the client, then run Verification.

Traps

• Secrets: if the user already has a GITHUB_TOKEN or Capgo API key in config, keep it as is. Prefer OAuth for Capgo hosted; use a key with the smallest role needed (read-only for reporting). Never commit keys in project-scoped config; use env vars or user scope.
• Capgo hosted tools include destructive ones (delete app, set channel bundle, roll back). Clients ask for confirmation; do not auto-approve them.
• OAuth sessions create a key named MCP · <client name> that expires after at most 90 days. Reconnect via /mcp when it expires; revoke by deleting that key in the console.
• awesome-ionic-mcp runs ionic/npx commands in project_directory (defaults to the nearest project root, then cwd). Only ionic, @ionic/cli, @capacitor/cli and cap* packages are allowed, and arguments containing ; & | $ ( ) { } [ ] < > are rejected.
• ionic_serve and capacitor_run block or need a device; prefer running them in a terminal the user controls.
• awesome-ionic-mcp parameters are html_tag (not tag), repo_name for Capgo/community plugins, plugin_name for official plugins, slug for the third-party catalog. Call the get_all_* tool first to get exact names.
• xcrun mcpbridge resolves Xcode via xcode-select. If the active developer dir is /Library/Developer/CommandLineTools, it is not found.
• Xcode approves per process: restarting the agent triggers a new approval prompt.
• Without the Intelligence setting enabled, xcrun mcpbridge connects but exposes no tools.

Verification

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

Then make one read-only tool call per server and confirm a real result:

• awesome-ionic-mcp: get_ionic_component_definition with html_tag: "ion-button", or get_all_capgo_plugins
• Capgo hosted: "List my Capgo apps"
• Capgo local: capgo_list_apps or capgo_doctor
• Xcode: ask the agent to build the iOS app (ios/App/App.xcodeproj or App.xcworkspace open in Xcode)

In Cursor/VS Code/Claude Desktop, check the MCP panel shows the server enabled with a tool count above zero.

Error Handling

References

Only load a reference when its topic is in play.

• references/awesome-ionic-mcp.md: client configs (Claude Desktop, Cursor, Cline, VS Code), full tool list with verified parameters, live viewer.
• references/capgo-mcp.md: hosted vs local Capgo MCP, per-client setup (Claude.ai, ChatGPT, Cursor, VS Code, Lovable, API-key headers), tool coverage.
• references/xcode-mcp.md: Xcode MCP bridge setup for Claude Code and Codex, run-agent, headless mcp-server commands, Capacitor iOS workflow.

Resources

• awesome-ionic-mcp: https://github.com/Tommertom/awesome-ionic-mcp
• Capgo hosted MCP: https://capgo.app/docs/ai/mcp/
• Capgo CLI MCP: https://capgo.app/docs/cli/reference/mcp/
• Xcode external agents: 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 spec: https://modelcontextprotocol.io