capacitor-mcp · diff
git:20260501.ed3e92e to git:20261011.86834d4
83 added, 396 removed. Audit A to A.
---
name: capacitor-mcp
- description: Model Context Protocol (MCP) tools for Capacitor mobile development. Covers Ionic/Capacitor component APIs, plugin documentation, CLI commands, and AI-assisted development via MCP. Use this skill when users want to integrate AI agents with Ionic/Capacitor tooling.
+ description: Connect AI agents (Claude Code, Claude Desktop, Cursor, VS Code, Cline, Codex) to Capacitor and Ionic tooling over Model Context Protocol. Covers the awesome-ionic-mcp server (Ionic component APIs, Capacitor plugin docs, Ionic/Capacitor CLI tools), the Capgo hosted MCP at https://api.capgo.app/mcp, the local Capgo CLI MCP (npx @capgo/cli@latest mcp), and Xcode's MCP bridge (xcrun mcpbridge) for building the iOS app from an agent. Use when the user wants to add, configure, verify, or troubleshoot an MCP server for a Capacitor project, or sees errors like "GitHub API rate limit exceeded", "unable to find utility \"mcpbridge\"", or an MCP server that connects with no tools. Do not use for Capgo account operations themselves (capgo-cloud, capgo-cli-usage), app debugging (debugging-capacitor), device logs (ios-android-logs), choosing plugins (capacitor-plugins), or Ionic UI work (ionic-design).
---
- # Capacitor MCP Tools
-
- Guide to using Model Context Protocol (MCP) for Ionic and Capacitor mobile development automation.
-
- ## When to Use This Skill
-
- - User wants to automate Ionic/Capacitor development
- - User asks about MCP integration
- - User wants AI-assisted component/plugin discovery
- - User needs programmatic CLI command execution
- - User wants access to Ionic components and Capacitor plugins within AI chat
-
- ## What is MCP?
-
- MCP (Model Context Protocol) is an open standard for connecting AI models to external tools and data sources. For Capacitor development, MCP enables:
-
- - Access to Ionic component definitions and APIs
- - Capacitor plugin documentation lookup
- - Automated CLI command execution (build, sync, run, etc.)
- - Project configuration management
- - Real-time component demos and examples
-
- ## Setting Up MCP for Capacitor
-
- ### 1. Install Awesome Ionic MCP Server
-
- The **awesome-ionic-mcp** server is a comprehensive tool that provides access to:
- - Ionic Framework component APIs
- - Official Capacitor plugins
- - third-party plugin catalogs
- - Capacitor Community plugins
- - CapGo plugins
- - 28 Ionic/Capacitor CLI commands
-
- #### Claude Desktop
-
- Add to `claude_desktop_config.json` (accessible via Claude > Settings > Developer):
-
- ```json
- {
- "mcpServers": {
- "awesome-ionic-mcp": {
- "command": "npx",
- "args": ["-y", "awesome-ionic-mcp@latest"]
- }
- }
- }
- ```
-
- #### Cline
-
- Add to `cline_mcp_settings.json`:
-
- ```json
- {
- "mcpServers": {
- "awesome-ionic-mcp": {
- "command": "npx",
- "args": ["-y", "awesome-ionic-mcp@latest"],
- "disabled": false
- }
- }
- }
- ```
-
- #### Cursor
-
- Add to `.cursor/mcp.json` (project-specific) or `~/.cursor/mcp.json` (global):
-
- ```json
- {
- "mcpServers": {
- "awesome-ionic-mcp": {
- "command": "npx",
- "args": ["-y", "awesome-ionic-mcp@latest"]
- }
- }
- }
- ```
-
- ### 2. Optional: GitHub Token for Rate Limiting
-
- The server makes ~160+ GitHub API calls during initialization to fetch plugin data. Without authentication, GitHub limits you to 60 requests/hour. With a token, this increases to 5,000 requests/hour.
-
- Add `GITHUB_TOKEN` to your MCP configuration:
-
- ```json
- {
- "mcpServers": {
- "awesome-ionic-mcp": {
- "command": "npx",
- "args": ["-y", "awesome-ionic-mcp@latest"],
- "env": {
- "GITHUB_TOKEN": "ghp_your_token_here"
- }
- }
- }
- }
- ```
-
- Get a token from GitHub Settings → Developer settings → Personal access tokens. No special permissions needed for public repos.
-
- ## Available MCP Tools
-
- ### Ionic Component Tools
-
- ```typescript
- // Get Ionic component definition
- get_ionic_component_definition({ tag: "ion-button" })
- // Returns TypeScript definition from @ionic/core
-
- // List all Ionic components
- get_all_ionic_components()
- // Returns: ["ion-button", "ion-card", "ion-input", ...]
-
- // Get component API documentation
- get_component_api({ tag: "ion-button" })
- // Returns API docs from ionicframework.com
-
- // Get component demo code
- get_component_demo({ tag: "ion-modal" })
- // Returns demo code from docs-demo.ionic.io
- ```
-
- ### Capacitor Plugin Tools
-
- ```typescript
- // Get official Capacitor plugin API
- get_official_plugin_api({ plugin: "Camera" })
- // Returns documentation from capacitorjs.com
-
- // List all official plugins
- get_all_official_plugins()
- // Returns: ["Camera", "Filesystem", "Geolocation", ...]
-
- // Search all available Capacitor plugins
- get_all_capacitor_plugins()
- // Returns superlist from all plugin publishers
-
- // Get third-party plugin documentation
- get_plugin_api({ plugin: "capacitor-firebase" })
-
- // List third-party plugins
- get_all_free_plugins() // Free plugins
- get_all_insider_plugins() // Insider/paid plugins
-
- // Get CapGo plugin documentation
- get_capgo_plugin_api({ plugin: "native-biometric" })
- get_all_capgo_plugins()
-
- // Get Capacitor Community plugin docs
- get_capacitor_community_plugin_api({ plugin: "http" })
- get_all_capacitor_community_plugins()
- ```
-
- ### Ionic CLI Commands
-
- All commands accept a `project_directory` parameter (defaults to current directory).
-
- #### Project Information
-
- ```typescript
- // Get comprehensive project info
- ionic_info({ format: "json" })
-
- // Get configuration value
- ionic_config_get({ key: "name" })
-
- // Set configuration value
- ionic_config_set({ key: "name", value: "MyApp" })
-
- // Unset configuration value
- ionic_config_unset({ key: "telemetry" })
- ```
-
- #### Project Setup
-
- ```typescript
- // Create new Ionic project
- ionic_start({
- name: "MyApp",
- template: "tabs", // blank, list, sidemenu, tabs
- type: "react", // angular, react, vue
- capacitor: true
- })
-
- // List available templates
- ionic_start_list()
-
- // Initialize existing project
- ionic_init({ name: "MyApp", type: "react" })
-
- // Repair project dependencies
- ionic_repair()
- ```
-
- #### Build & Serve
-
- ```typescript
- // Build web assets
- ionic_build({
- project_directory: "./my-app",
- prod: true,
- engine: "browser" // or "cordova"
- })
-
- // Start development server (manual launch recommended)
- // Note: Server runs in foreground, manual launch preferred
- ionic_serve({
- project_directory: "./my-app",
- port: 8100,
- lab: false
- })
- ```
-
- #### Code Generation
-
- ```typescript
- // Generate page
- ionic_generate({
- type: "page",
- name: "home",
- project_directory: "./my-app"
- })
-
- // Generate component
- ionic_generate({
- type: "component",
- name: "user-card"
- })
-
- // Generate service
- ionic_generate({
- type: "service",
- name: "auth"
- })
-
- // Other types: directive, guard, pipe, class, interface, module
- ```
-
- #### Integrations
-
- ```typescript
- // List available integrations
- integrations_list()
-
- // Enable integration (e.g., Capacitor)
- integrations_enable({ integration: "capacitor" })
-
- // Disable integration
- integrations_disable({ integration: "cordova" })
- ```
-
- ### Capacitor CLI Commands
-
- #### Project Management
-
- ```typescript
- // Check Capacitor setup
- capacitor_doctor({ platform: "ios" })
-
- // List installed plugins
- capacitor_list_plugins()
-
- // Initialize Capacitor
- capacitor_init({
- name: "MyApp",
- id: "com.example.app",
- web_dir: "dist"
- })
-
- // Add platform
- capacitor_add({ platform: "ios" })
- capacitor_add({ platform: "android" })
-
- // Migrate to latest version
- capacitor_migrate()
- ```
-
- #### Build & Sync
-
- ```typescript
- // Sync web assets and dependencies
- capacitor_sync({ platform: "ios" })
-
- // Copy web assets only
- capacitor_copy({ platform: "android" })
-
- // Update native dependencies
- capacitor_update({ platform: "ios" })
-
- // Build native release
- capacitor_build({
- platform: "ios",
- scheme: "App",
- configuration: "Release"
- })
- ```
-
- #### Run & Deploy
+ # Capacitor MCP Servers
- ```typescript
- // Run on device/emulator
- capacitor_run({
- platform: "ios",
- target: "iPhone 15 Pro"
- })
+ Wire MCP servers into an agent so it can read Ionic/Capacitor docs, run Capacitor CLI commands, manage Capgo, and drive Xcode.
- // Open native IDE
- capacitor_open({ platform: "ios" }) // Opens Xcode
- capacitor_open({ platform: "android" }) // Opens Android Studio
- ```
+ ## When to Use
- ## Common Workflows
+ 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
- ### Create New Project
+ 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`
- ```typescript
- // 1. Create Ionic project
- ionic_start({
- name: "MyApp",
- template: "tabs",
- type: "react",
- capacitor: true
- })
+ ## Pick the Server
- // 2. Add iOS platform
- capacitor_add({
- project_directory: "./MyApp",
- platform: "ios"
- })
+ | 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 |
- // 3. Build and sync
- ionic_build({
- project_directory: "./MyApp",
- prod: true
- })
- capacitor_sync({
- project_directory: "./MyApp",
- platform: "ios"
- })
- ```
+ 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.
- ### Check Project Health
+ ## Procedure
- ```typescript
- // Get system info
- ionic_info({ format: "json" })
+ 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:
- // Check Capacitor setup
- capacitor_doctor({ platform: "ios" })
+ ```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
+ ```
- // List installed plugins
- capacitor_list_plugins()
- ```
+ 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.
- ### Generate Code
+ ## Traps
- ```typescript
- // Generate page with routing
- ionic_generate({ type: "page", name: "profile" })
+ - 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.
- // Generate reusable component
- ionic_generate({ type: "component", name: "user-avatar" })
+ ## Verification
- // Generate service
- ionic_generate({ type: "service", name: "data" })
+ ```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
```
- ## AI-Assisted Development Benefits
-
- With awesome-ionic-mcp, AI assistants can:
-
- 1. **Discover Components**: Ask "What Ionic components can I use for forms?" and get accurate API docs
- 2. **Find Plugins**: Ask "Is there a Capacitor plugin for biometric authentication?" and get relevant results
- 3. **Execute Commands**: Request "Build the iOS app" and the CLI command runs automatically
- 4. **Generate Code**: Get component examples with proper TypeScript definitions
- 5. **Troubleshoot**: Look up plugin APIs and configuration without leaving the chat
-
- ## Example Queries
-
- With the MCP server installed, you can ask your AI assistant:
-
- - "Show me the API for ion-modal component"
- - "List all available Capacitor Camera plugin methods"
- - "Generate a new page called settings"
- - "What third-party plugins are available for Firebase?"
- - "Build my app for iOS"
- - "Sync my Capacitor project"
- - "What are all the free CapGo plugins?"
-
- ## Technical Details
+ 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)
- ### Data Sources
+ In Cursor/VS Code/Claude Desktop, check the MCP panel shows the server enabled with a tool count above zero.
- The awesome-ionic-mcp server aggregates data from:
- - `@ionic/core` package (TypeScript definitions)
- - ionicframework.com (component API docs)
- - docs-demo.ionic.io (component demos)
- - capacitorjs.com (official plugins)
- - third-party plugin catalogs
- - capacitor-community (community plugins)
- - capgo.app (CapGo plugins)
+ ## Error Handling
- ### Requirements
+ | 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`. |
- - Node.js (for npx command)
- - Optional: GitHub token for avoiding API rate limits
- - Ionic/Capacitor project (for CLI commands)
+ ## References
- ### Browser Automation
+ Only load a reference when its topic is in play.
- The server uses Puppeteer to fetch some documentation. You may see a browser window spawn and close during initialization - this is normal.
+ - `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
- - MCP Specification: https://modelcontextprotocol.io
- - MCP SDK: https://github.com/modelcontextprotocol/sdk
- - Ionic Framework: https://ionicframework.com
- - Capacitor: https://capacitorjs.com
- - CapGo Plugins: https://capgo.app
+ - 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