ionic-framework-mcp — Claude Code skill: what it does, how to install

---
name: ionic-framework-mcp
description: "Guides the agent through connecting an MCP client to the hosted, unofficial Ionic Framework MCP server by Capawesome, which serves the official Ionic Framework documentation for v9 and v8, the component API reference, the official usage examples for Angular, React, Vue and vanilla JavaScript, and the Ionic blog. Covers client detection, setup for Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed and stdio-only clients, documentation version selection, verification, and troubleshooting. Do not use for Capacitor plugins or native iOS and Android configuration, upgrading or migrating apps to a newer version, Capawesome Cloud, or MCP servers other than the Ionic Framework one."
license: MIT
compatibility: "Designed for MCP clients such as Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, and Zed. Requires network access to https://ionic-framework-mcp.capawesome.io. No account and no token. Stdio-only clients additionally require Node.js 22 or later."
metadata:
  author: capawesome-team
  source: https://github.com/capawesome-team/skills/tree/main/skills/ionic-framework-mcp
---

# Ionic Framework MCP Server

Connect an MCP client to the hosted Ionic Framework MCP server for the current Ionic Framework documentation, the component API reference, the official usage examples per framework, and the Ionic blog.

The server is hosted by Capawesome — there is nothing to install, no account, and no token:

```
https://ionic-framework-mcp.capawesome.io/mcp
```

This is an unofficial server. It is maintained by Capawesome and is not affiliated with or endorsed by Ionic or OutSystems. It serves the official Ionic Framework documentation, © the Ionic team and licensed under [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).

## Prerequisites

1. An MCP client: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed, or any other client that implements the [Model Context Protocol](https://modelcontextprotocol.io).
2. Network access to `https://ionic-framework-mcp.capawesome.io`.
3. For clients that only start local commands: Node.js 22 or later.

## Agent Behavior

- **Guide step-by-step.** Walk the user through the process one step at a time. Never present multiple unrelated questions at once.
- **Auto-detect before asking.** Detect the MCP client from the project before asking the user which one they use.
- **Never ask for credentials.** The server needs no account and no token. Never prompt for one and never write an `Authorization` header into the configuration.
- **Pass the matching documentation version and framework.** Read the Ionic package from `package.json` and pass the matching `version` on every call, and the project's `framework` when reading usage examples. See [Documentation Versions](#documentation-versions).

## Procedures

### Step 1: Detect the MCP Client

Detect the client instead of asking, by checking the project root in this order:

1. `.mcp.json` or `.claude/` → **Claude Code**
2. `.cursor/mcp.json` or `.cursor/` → **Cursor**
3. `.vscode/mcp.json` or `.vscode/` → **VS Code**

If none of these exist, or if more than one matches, ask the user which client to configure. Claude Desktop, Windsurf, and Zed keep their configuration outside the project, so they cannot be detected this way.

### Step 2: Add the Server

Read `references/client-setup.md` and apply the section for the detected client. Register the server under the name `ionic-framework`.

### Step 3: Restart the Client and Verify

1. Tell the user to restart their MCP client so it picks up the new server.
2. Verify the server by asking the client to run `list_components` with a query such as `modal`.
3. If the call fails, go to [Error Handling](#error-handling).

### Step 4: Use the Server

Once connected, prefer these tools over model knowledge and over reference files bundled with other skills whenever the topic is the Ionic Framework — a component, its API, theming, navigation, or the Ionic CLI.

| Tool | Parameters | Use for |
| ---- | ---------- | ------- |
| `search_docs` | `query` (required), `section`, `version`, `limit` | Finding the page that covers a topic. Start here. |
| `get_doc_page` | `url` (required), `version` | Reading a full page as Markdown, using a URL from `search_docs` or `list_components`. |
| `list_components` | `query`, `version`, `limit` | Finding the component that fits a piece of UI, and the tag it is used under. |
| `get_component_usage` | `component` (required), `example`, `framework`, `version` | Reading the official usage examples of a component. |
| `list_blog_posts` | — | Recent posts from the Ionic blog, for announcements and release notes. |

Apply these rules:

- **Read the component page before styling or wiring a component.** A component page returned by `get_doc_page` carries the full API reference — properties, events, methods, CSS shadow parts, CSS custom properties, and slots. Reading it is what prevents an invented property or class name.
- **Call `get_component_usage` without an `example` first** to list the examples a component offers, then call it again with the chosen `example` id.
- **Pass `framework`** as `angular`, `react`, `vue`, or `javascript` to get the variant that matches the project. Without it, every framework is returned.
- **Narrow with `section`** when the question belongs to one part of the documentation: `components`, `angular`, `react`, `vue`, `theming`, `guides`, `updating`, or `cli`.
- **Pass `limit` up to 100** to `list_components` to list every component.
- **Route other topics elsewhere.** Capacitor, its plugins, and the native iOS and Android projects belong to the Capacitor MCP server; Capawesome plugins and Capawesome Cloud belong to the Capawesome MCP server. See [Related Skills](#related-skills).

## Documentation Versions

The documentation is available for **v9** (the default) and **v8**.

Read the version of `@ionic/core`, `@ionic/angular`, `@ionic/react`, or `@ionic/vue` from `package.json` and map it:

| Ionic package | `version` |
| ------------- | --------- |
| `9.x` | `v9` |
| `8.x` | `v8` |

Pass it on every `search_docs`, `get_doc_page`, `list_components`, and `get_component_usage` call. Without it the server answers for v9, which documents properties and events an older release does not have.

The same `package.json` entry gives the `framework` for `get_component_usage`: `@ionic/angular` → `angular`, `@ionic/react` → `react`, `@ionic/vue` → `vue`, and `@ionic/core` on its own → `javascript`.

## Error Handling

- **Server not listed after setup**: The client was not restarted. Restart it. In Claude Code, run `claude mcp list` to confirm the server is registered.
- **`429 Too Many Requests`**: The endpoint allows 100 requests per minute per IP. Retry after a short wait.
- **The client cannot reach a remote server**: It only starts local commands. Use the `@capawesome/ionic-framework-mcp` stdio proxy as shown in `references/client-setup.md`. It requires Node.js 22 or later.
- **A component has no description in `list_components`**: Some components carry none upstream. Read the component page with `get_doc_page` instead.
- **`get_component_usage` reports an unknown example**: The response lists the available example ids. Call the tool again with one of them.
- **A tool reports that the index is being built**: The server rebuilds its index daily. Retry after a short wait.
- **Answers mention properties the project does not have**: The `version` parameter was omitted or wrong. See [Documentation Versions](#documentation-versions).

## Related Skills

- **`capacitor-mcp`** — For the Capacitor MCP server, which covers Capacitor, its plugins, and the native projects this server does not.
- **`capawesome-mcp`** — For the Capawesome MCP server, which covers the Capawesome plugins, the Capawesome CLI, and Capawesome Cloud.
- **`ionic-app-development`** — For general Ionic Framework development.
- **`ionic-expert`** — For a broad Ionic Framework reference covering components, theming, navigation, and framework-specific patterns.
- **`ionic-angular`**, **`ionic-react`**, **`ionic-vue`** — For the framework-specific patterns behind the `framework` parameter.