capacitor-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capacitor MCP Server

Capacitor MCP 服务器

Connect an MCP client to the hosted Capacitor MCP server for the current Capacitor documentation, the official and community plugin list, and the Capacitor posts from the Ionic blog.

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

https://capacitor-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 Capacitor documentation, © the Ionic team and licensed under Apache-2.0.

将 MCP 客户端连接到托管的 Capacitor MCP 服务器，以获取当前 Capacitor 文档、官方及社区插件列表，以及 Ionic 博客中的 Capacitor 文章。

该服务器由 Capawesome 托管——无需安装任何内容，无需账户，也无需 token：

https://capacitor-mcp.capawesome.io/mcp

这是一个非官方服务器，由 Capawesome 维护，与 Ionic 或 OutSystems 无隶属关系，也未获得其认可。服务器提供官方 Capacitor 文档，© Ionic 团队，并采用 Apache-2.0 许可。

Prerequisites

前置条件

An MCP client: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed, or any other client that implements the Model Context Protocol.
Network access to
```
https://capacitor-mcp.capawesome.io
```
.
For clients that only start local commands: Node.js 22 or later.

一个 MCP 客户端：Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Zed，或任何其他实现了 Model Context Protocol 的客户端。
能够访问
```
https://capacitor-mcp.capawesome.io
```
的网络连接。
对于只能启动本地命令的客户端：Node.js 22 或更高版本。

Agent Behavior

Agent 行为

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. Read
```
@capacitor/core
```
from
```
package.json
```
and pass the matching
```
version
```
on every call. See Documentation Versions.

逐步指导。 每次只引导用户完成一个步骤。绝不要一次提出多个互不相关的问题。
先自动检测，再询问。 在询问用户使用哪个客户端之前，先从项目中检测 MCP 客户端。
绝不索要凭据。 该服务器不需要账户，也不需要 token。绝不提示用户提供凭据，也绝不要在配置中写入
```
Authorization
```
请求头。
传入匹配的文档版本。 从
```
package.json
```
中读取
```
@capacitor/core
```
，并在每次调用时传入匹配的
```
version
```
。参见文档版本。

Procedures

操作流程

Step 1: Detect the MCP Client

第 1 步：检测 MCP 客户端

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

```
.mcp.json
```
or
```
.claude/
```
→ Claude Code
```
.cursor/mcp.json
```
or
```
.cursor/
```
→ Cursor
```
.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.

不要直接询问用户，而应按以下顺序检查项目根目录来检测客户端：

```
.mcp.json
```
或
```
.claude/
```
→ Claude Code
```
.cursor/mcp.json
```
或
```
.cursor/
```
→ Cursor
```
.vscode/mcp.json
```
或
```
.vscode/
```
→ VS Code

如果以上目录均不存在，或匹配到多个客户端，请询问用户要配置哪个客户端。Claude Desktop、Windsurf 和 Zed 将配置保存在项目之外，因此无法通过这种方式检测。

Step 2: Add the Server

第 2 步：添加服务器

Read

references/client-setup.md

and apply the section for the detected client. Register the server under the name

capacitor

读取

references/client-setup.md

，并应用检测到的客户端所对应的章节。以

capacitor

为名称注册该服务器。

Step 3: Restart the Client and Verify

第 3 步：重启客户端并验证

Tell the user to restart their MCP client so it picks up the new server.
Verify the server by asking the client to run
```
search_docs
```
with a query such as
```
live reload
```
.
If the call fails, go to Error Handling.

告知用户重启 MCP 客户端，使其加载新服务器。
让客户端使用
```
live reload
```
等查询运行
```
search_docs
```
，以验证服务器。
如果调用失败，请转到错误处理。

Step 4: Use the Server

第 4 步：使用服务器

Once connected, prefer these tools over model knowledge and over reference files bundled with other skills whenever the topic is Capacitor itself — the CLI, the

capacitor.config

file, the native Android and iOS projects, an official plugin API, or upgrading to a newer major version.

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` .
`list_plugins`	`query` , `source` , `limit`	Finding a plugin for a native capability.
`list_blog_posts`	—	Recent Capacitor posts from the Ionic blog, for announcements and release notes.

Apply these rules:

Read the whole page before writing code. Search snippets are deliberately short and regularly omit required configuration steps.

Narrow with
section
when the question belongs to one part of the documentation:

getting-started

basics

guides

android

ios

web

plugins

apis

cli

reference

updating

, or

cordova

Pass
source
to
list_plugins
as
```
official
```
,
```
community
```
, or
```
all
```
(the default). Results are ranked official plugins first, then plugins maintained by Capawesome, then the remaining community plugins. The server discloses that ranking in its response, so weigh the order instead of treating it as neutral relevance.
Route other topics elsewhere. Capawesome plugins and Capawesome Cloud belong to the Capawesome MCP server; Ionic Framework UI components belong to the Ionic Framework MCP server. See Related Skills.

连接完成后，只要主题涉及 Capacitor 本身——例如 CLI、

capacitor.config

文件、原生 Android 和 iOS 项目、官方插件 API，或升级到较新的主版本——都应优先使用这些工具，而不是模型知识或其他 skill 捆绑的参考文件。

工具	参数	用途
`search_docs`	`query` （必填）、 `section` 、 `version` 、 `limit`	查找涵盖某个主题的页面。请从此开始。
`get_doc_page`	`url` （必填）、 `version`	使用 `search_docs` 返回的 URL，以 Markdown 格式读取完整页面。
`list_plugins`	`query` 、 `source` 、 `limit`	查找提供原生功能的插件。
`list_blog_posts`	—	获取 Ionic 博客中最近的 Capacitor 文章，包括公告和发布说明。

应用以下规则：

编写代码前阅读完整页面。 搜索摘要刻意保持简短，通常会省略必需的配置步骤。
使用
section
缩小范围。当问题仅属于文档中的某个部分时，使用
```
getting-started
```
、
```
basics
```
、
```
guides
```
、
```
android
```
、
```
ios
```
、
```
web
```
、
```
plugins
```
、
```
apis
```
、
```
cli
```
、
```
reference
```
、
```
updating
```
或
```
cordova
```
。
调用
list_plugins
时传入
source
。可取
```
official
```
、
```
community
```
或
```
all
```
（默认值）。结果会优先排列官方插件，其次是由 Capawesome 维护的插件，最后是其他社区插件。服务器会在响应中说明这一排序规则，因此应结合排序权重进行判断，不要将结果顺序视为中立的相关性排序。
将其他主题转至相应的 skill。 Capawesome 插件和 Capawesome Cloud 属于 Capawesome MCP 服务器的范畴；Ionic Framework UI 组件属于 Ionic Framework MCP 服务器的范畴。参见相关 skill。

Documentation Versions

文档版本

The documentation is available for v8 (the default), v7, v6, and next (the unreleased version).

Read the

@capacitor/core

version from

package.json

and map it:

`@capacitor/core`	`version`
`8.x`	`v8`
`7.x`	`v7`
`6.x`	`v6`
A pre-release of the next major	`next`

Pass it on every

search_docs

and

get_doc_page

call. Without it the server answers for v8, which documents APIs and CLI flags an older release does not have.

list_plugins

and

list_blog_posts

take no version.

文档提供 v8（默认版本）、v7、v6 和 next（未发布版本）。

从

package.json

中读取

@capacitor/core

版本，并按以下方式映射：

`@capacitor/core`	`version`
`8.x`	`v8`
`7.x`	`v7`
`6.x`	`v6`
下一个主版本的预发布版	`next`

每次调用

search_docs

和

get_doc_page

时都应传入该版本。如果不传入，服务器会基于 v8 回答，而 v8 中记录的某些 API 和 CLI 标志在较早版本中并不存在。

list_plugins

和

list_blog_posts

不接受版本参数。

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/capacitor-mcp
```
stdio proxy as shown in
```
references/client-setup.md
```
. It requires Node.js 22 or later.
A search returns no results: The index matches whole words, so a two-word guess such as
```
file system
```
misses
```
filesystem
```
. Retry with fewer, more general keywords, or with the exact package name.
A tool reports that the index is being built: The server rebuilds its index daily. Retry after a short wait.
Answers mention APIs the project does not have: The
```
version
```
parameter was omitted or wrong. See Documentation Versions.

配置后未列出服务器：客户端尚未重启。请重启客户端。在 Claude Code 中，运行
```
claude mcp list
```
以确认服务器已注册。
429 Too Many Requests
：该端点允许每个 IP 每分钟发送 100 个请求。请短暂等待后重试。
客户端无法连接远程服务器：该客户端只能启动本地命令。请按照
```
references/client-setup.md
```
中的说明使用
```
@capawesome/capacitor-mcp
```
stdio 代理。这需要 Node.js 22 或更高版本。
搜索没有返回结果：索引按完整单词匹配，因此像
```
file system
```
这样的双词猜测无法匹配
```
filesystem
```
。请使用更少、更通用的关键词或准确的 package 名称重试。
工具提示正在构建索引：服务器每天都会重建索引。请短暂等待后重试。
回答提及项目中不存在的 API：
```
version
```
参数被省略或填写错误。参见文档版本。