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

| Need | Server | Transport | | --- | --- | --- | | Ionic component APIs/demos, Capacitor plugin docs, run ionic/cap commands | awesome-ionic-mcp (community, npm) | stdio via npx | | Capgo account: apps, bundles, channels, rollouts, devices, stats, build status/logs, webhooks, push | Capgo hosted MCP https://api.capgo.app/mcp | streamable HTTP, OAuth or API key | | Upload a bundle from dist/, request a native build, doctor, probe, compatibility check | Capgo local CLI MCP npx @capgo/cli@latest mcp | stdio | | Build/run the iOS project, read Xcode issues, Xcode tools | Xcode MCP xcrun mcpbridge (Xcode 26.3+, verified on Xcode 27.1) | stdio |

The Capgo hosted and local servers are complementary: hosted cannot read local files; local needs npx @capgo/cli@latest login first. https://capgo.app/mcp is a separate public docs-discovery server with no account access.

Procedure

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.
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.

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.

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.
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

| Error / symptom | Fix | | --- | --- | | GitHub API rate limit exceeded. Set GITHUB_TOKEN environment variable to increase limits. | Add GITHUB_TOKEN (no scopes needed for public repos) to the server env, restart. | | Plugin not found: <name> (awesome-ionic-mcp) | Use the exact repo_name/slug returned by the matching get_all_* tool. | | Component not found: <tag> | Pass a real Ionic tag such as ion-modal; list with get_all_ionic_components. | | Command '<cmd>' is not allowed / NPX package '<pkg>' is not allowed / Argument contains dangerous characters | The server only runs Ionic/Capacitor CLIs with plain args; run other commands in a terminal. | | Failed to download core JSON data from Ionic. | Network issue at startup; check connectivity/proxy and restart the server. | | xcrun: error: unable to find utility "mcpbridge", not a developer tool or in PATH | sudo xcode-select -s /Applications/Xcode.app/Contents/Developer, or update Xcode to 26.3+. | | Xcode server connected but zero tools | Enable external agents in Xcode Settings > Intelligence and open the project. | | Capgo hosted shows "needs authentication" | Run /mcp (Claude Code) or click the client's login prompt; reconnect after the 90-day key expiry. | | Capgo local tools fail with auth errors | Run npx @capgo/cli@latest login on that machine. | | Server starts then exits in Claude Desktop | Node/npx not on the GUI PATH; use an absolute path to npx in command. |

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