> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/wen-dang-ji-dai-ma/gitbook-mcp.md).
# GitBook MCP
GitBook 提供了一个 MCP 服务器，让 AI 工具能够对你组织中的内容执行操作。
Claude Code、Codex、Cursor 以及其他 MCP 客户端等工具可以用它来创建和配置站点、打开变更请求、起草内容、编辑页面以及重组文档。
安装我们的官方插件：
安装 Claude 插件 安装 ChatGPT 插件 安装 Cursor 插件
{% hint style="info" %}
需要一个用于已发布文档站点的只读 MCP 服务器吗？GitBook 会自动为你创建一个——参见 [已发布文档的 MCP 服务器](/docs/documentation/zh/mian-xiang-du-zhe-de-ai/mcp-servers-for-published-docs.md) 了解更多。
{% endhint %}
## GitBook 的 MCP 端点
将你的 MCP 客户端指向：
```http
https://mcp.gitbook.com/mcp
```
{% hint style="info" %}
在浏览器中打开此 URL 会返回错误。请在可以发起 HTTP 请求的 MCP 客户端中使用它。
{% endhint %}
## 连接你的客户端
在你选择的客户端中添加 GitBook MCP：
{% tabs %}
{% tab title="Claude" icon="claude" %}
为 Claude 安装官方 GitBook 插件：
安装 Claude 插件
或者从终端添加该服务器：
```bash
claude mcp add --transport http gitbook https://mcp.gitbook.com/mcp
```
然后使用以下命令启动 Claude Code： `claude` 并运行 `/mcp` 以完成浏览器登录。
如果你更喜欢使用个人访问令牌，请将其作为授权头传递：
```bash
claude mcp add --transport http gitbook https://mcp.gitbook.com/mcp \
--header "Authorization: Bearer "
```
{% endtab %}
{% tab title="ChatGPT" icon="openai" %}
为 ChatGPT 安装官方 GitBook 插件：
安装 ChatGPT 插件
或者从终端添加该服务器：
```bash
codex mcp add gitbook --url https://mcp.gitbook.com/mcp
```
然后通过浏览器登录。
如果你想改用个人访问令牌，请将以下内容添加到 `~/.codex/config.toml`:
```toml
[mcp_servers.gitbook]
url = "https://mcp.gitbook.com/mcp"
bearer_token_env_var = "GITBOOK_MCP_TOKEN"
enabled = true
```
{% endtab %}
{% tab title="Cursor" icon="cursor" %}
为 Cursor 安装官方 GitBook 插件：
安装 Cursor 插件
或者将服务器添加到 `~/.cursor/mcp.json`，或者添加到你的项目中： `.cursor/mcp.json`:
```json
{
"mcpServers": {
"gitbook": {
"url": "https://mcp.gitbook.com/mcp"
}
}
}
```
然后在 Cursor 提示你时登录。
{% endtab %}
{% tab title="VS Code" icon="vscode" %}
将服务器添加到 `.vscode/mcp.json` 中：
```json
{
"servers": {
"gitbook": {
"type": "http",
"url": "https://mcp.gitbook.com/mcp"
}
}
}
```
然后从 MCP 视图启动它并登录。
{% endtab %}
{% tab title="其他" %}
任何兼容 MCP 的客户端都可以通过可流式 HTTP 连接。
将其指向：
```
https://mcp.gitbook.com/mcp
```
GitBook 仅支持可流式 HTTP。 `stdio` 并 `SSE` 不受支持。
如果你使用 OAuth，通常不需要任何额外的认证字段。
如果你改用个人访问令牌，请将其作为 bearer token 发送：
```http
Authorization: Bearer
```
{% endtab %}
{% endtabs %}
## 对 GitBook 的 MCP 进行身份验证
GitBook MCP 支持两种身份验证方式：OAuth 和个人访问令牌。
{% tabs %}
{% tab title="OAuth" %}
将你的客户端指向 MCP 服务器 URL。客户端会发现授权服务器、注册自身，并自动打开浏览器登录流程。
如果你使用 OAuth，请不要手动添加 bearer token。客户端会在登录过程中获取它。
{% endtab %}
{% tab title="个人访问令牌" %}
如果你想跳过浏览器流程，请将你的令牌作为 bearer token 发送：
```http
Authorization: Bearer
```
你可以在你的 [开发者设置](https://app.gitbook.com/account/developer).
对于脚本化设置，或者当你的客户端已经在本地管理密钥时，可使用这个。
{% endtab %}
{% endtabs %}
## 使用 GitBook 的 MCP
{% prompt description="Create and configure a new docs site." %}
```markdown
使用 GitBook MCP 工具，帮我创建一个新的文档站点。
1. 列出我的组织，并在创建任何内容之前确认要使用哪一个。
2. 问我这个站点是做什么的，以及我有哪些内容（文件夹、仓库，或者只是一个描述）。如果我给你一个来源，请把你在那里找到的内容回显给我，以便我确认是否正确。
3. 给我一个简短的计划——站点名称、空间、页面结构——然后等待我的确认。
4. 创建站点，添加内容，并发布。然后获取线上 URL 来确认它可用，并把它分享给我。
```
{% endprompt %}
{% prompt description="Open a change request and draft content." %}
```markdown
使用 GitBook MCP 工具，在变更请求中为我的文档起草新内容——不要编辑任何线上内容。
1. 列出我的组织和站点，并确认要在哪个空间中工作。
2. 问我内容应该涵盖什么，然后打开一个变更请求并在其中起草页面。
3. 匹配我现有页面的语气和结构——先读几页。
4. 完成后，分享变更请求预览链接，以便我在 GitBook 中审查并合并它。
```
{% endprompt %}
{% prompt description="Move, rename, or restructure pages across a site." %}
```markdown
使用 GitBook MCP 工具，帮我重组文档站点。
1. 列出我的组织和站点，确认是哪一个，然后获取其当前结构并展示给我。
2. 问我想改什么，然后以一个简单的修改前/后树形结构提出新结构——在我批准之前不要移动任何东西。
3. 应用更改，尽可能保持 URL 和内部链接不变；标记任何会失效的内容。
4. 向我展示最终结构以及变更请求或线上结果，以便验证。
```
{% endprompt %}
## GitBook MCP 与已发布文档 MCP 的区别
GitBook 有两种 MCP 模式：
* [**已发布文档的 MCP 服务器**](/docs/documentation/zh/mian-xiang-du-zhe-de-ai/mcp-servers-for-published-docs.md) 让 AI 工具对已发布内容具有只读访问权限。
* **GitBook MCP** 通过 GitBook API 让 AI 工具访问你的内容和工作流。
当你希望文档读者和最终用户能从已发布文档中查找信息时，请使用已发布文档 MCP。
当你希望团队的代理通过自动化工作流编辑和管理文档时，请使用 GitBook MCP。
## 常见问题
当我连接 MCP 客户端时，GitBook MCP 支持哪种传输方式？
GitBook MCP 支持可流式 HTTP。
GitBook MCP 不支持 `stdio` 或者 `SSE`.
如果你的客户端要求额外字段，通常可以将它们留空。
当我将客户端连接到 GitBook MCP 时，是否需要添加 bearer token？
你只需要在使用 [个人访问令牌](https://app.gitbook.com/account/developer).
如果你使用 OAuth，请不要手动添加 bearer token。你的客户端会在登录流程中获取它。
为什么我把 GitBook MCP 服务器添加到客户端后没有任何反应？
是的。这在某些 MCP 客户端中是预期行为。
添加服务器通常只是保存配置。某些客户端只有在首次连接、列出工具或打开 MCP 面板时才会开始身份验证。
为什么我点击 GitBook MCP 的 Authenticate 后没有任何反应？
某些客户端会在短暂延迟后打开浏览器登录流程。
在网络缓慢或不稳定时，这个延迟可能会更长。
如果大约一分钟后仍未打开浏览器标签页，请检查你的网络、弹窗设置和默认浏览器。
GitBook MCP 的身份验证流程中会发生什么？
当身份验证成功时，流程通常如下：
1. 客户端连接到 MCP 服务器。
2. 你的浏览器打开登录流程。
3. 你登录并批准访问。
4. 客户端会显示服务器已连接，或者 MCP 工具变得可用。
我怎么判断我的客户端是否已成功通过 GitBook MCP 认证？
具体信号取决于你的客户端，但结果通常很明确。
大多数客户端会移除认证提示，显示服务器已连接，或允许助手列出并调用 MCP 工具。
如果 **Authenticate** 按钮仍然可见且没有出现工具，流程很可能没有完成。
如果 GitBook MCP 身份验证仍然似乎卡住了，我应该检查什么？
请尝试以下检查：
* 确认服务器 URL 指向 MCP 端点。
* 确认客户端使用 HTTP 传输。
* 在稳定的网络环境下重试。
* 如果客户端缓存了失败状态，请移除并重新添加服务器。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://gitbook.com/docs/documentation/zh/wen-dang-ji-dai-ma/gitbook-mcp.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.