capacitor-mcp

Files (5)

• SKILL.md
• metadata.json
• awesome-ionic-mcp.md · references/
• capgo-mcp.md · references/
• xcode-mcp.md · references/

SKILL.md (first lines)

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

   ```bash
   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

```bash
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

From Cap-go/capgo-skills, MIT.

More from Cap-go/capgo-skills