> 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/docs-as-code/gitbook-mcp.md).

# GitBook MCP

将 AI 编程助手连接到 GitBook，使其可以创建站点、发起变更请求，并通过 GitBook 的 API 编辑内容

GitBook 提供了一个 MCP 服务器，可让 AI 工具对你组织中的内容进行操作。

Claude Code、Codex、Cursor 等工具以及其他 MCP 客户端可以用它来创建和配置站点、发起变更请求、起草内容、编辑页面，以及重组文档。

<p align="center">安装我们的官方插件：</p>

<p align="center"><a href="https://claude.ai/directory/connectors/gitbook-mcp" class="button secondary" data-icon="claude">安装 Claude 插件</a> <a href="https://chatgpt.com/apps/gitbook/asdk_app_6a576f075ec4819196c203b7049542be" class="button secondary" data-icon="openai">安装 ChatGPT 插件</a> <a href="https://cursor.com/marketplace/gitbook" class="button secondary" data-icon="cursor">安装 Cursor 插件</a></p>

{% hint style="info" %}
需要为已发布的文档站点配置只读 MCP 服务器？GitBook 会自动为你创建一个，详情请参阅 [已发布文档的 MCP 服务器](https://gitbook.com/docs/documentation/zh/ai-for-your-readers/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 插件：

<a href="https://claude.ai/directory/connectors/gitbook-mcp" class="button secondary" data-icon="claude">安装 Claude 插件</a>

或者从终端添加服务器：

```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 <YOUR_TOKEN>"
```

{% endtab %}

{% tab title="ChatGPT" icon="openai" %}
为 ChatGPT 安装官方 GitBook 插件：

<a href="https://chatgpt.com/apps/gitbook/asdk_app_6a576f075ec4819196c203b7049542be" class="button secondary" data-icon="openai">安装 ChatGPT 插件</a>

或者从终端添加服务器：

```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 插件：

<a href="https://cursor.com/marketplace/gitbook" class="button secondary" data-icon="cursor">安装 Cursor 插件</a>

或者将服务器添加到 `~/.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 <YOUR_PAT>
```

{% endtab %}
{% endtabs %}

## 对 GitBook 的 MCP 进行身份验证

GitBook MCP 支持两种身份验证方式：OAuth 和个人访问令牌。

{% tabs %}
{% tab title="OAuth" %}
将你的客户端指向 MCP 服务器 URL。客户端会发现授权服务器，注册自身，并自动打开浏览器登录流程。

如果你使用 OAuth，不要手动添加 bearer token。客户端会在登录过程中获取它。
{% endtab %}

{% tab title="个人访问令牌" %}
如果想跳过浏览器流程，请将你的令牌作为 bearer token 发送：

```http
Authorization: Bearer <YOUR_PAT>
```

你可以在 [开发者设置](https://app.gitbook.com/account/developer).

中创建个人访问令牌。可用于脚本化设置，或当你的客户端已在本地管理密钥时。
{% endtab %}
{% endtabs %}

## 使用 GitBook 的 MCP

第一次设置 GitBook？请改为让你的智能体访问 [设置 GitBook](https://gitbook.com/docs/documentation/zh/setup.md) 。

{% 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 不会根据你的套餐（包括免费套餐）设置使用配额。它会使用你的令牌调用 GitBook API，因此适用 API 速率限制：每个令牌每小时 5,000 次请求。读取和写入请求计数相同。

* 一次 MCP 工具调用可能会发出多个 API 请求，因此限制并不等同于每小时恰好 5,000 次工具调用。
* 邀请成员的频率限制为每分钟 2 次。
* 超过限制时，调用会失败，并显示“超出速率限制”错误，告知你需要等待多少秒才能重试。

你的套餐仍决定你可以执行哪些操作。如果某次调用需要的功能不包含在你的套餐中，GitBook 会像在应用中一样拒绝该调用，并提供升级链接。

## GitBook MCP 与已发布文档 MCP 的区别

GitBook 有两种 MCP 模式：

* [**中创建个人访问令牌。**](https://gitbook.com/docs/documentation/zh/ai-for-your-readers/mcp-servers-for-published-docs.md) 已发布文档的 MCP 服务器可让 AI 工具以只读方式访问已发布的内容。
* **GitBook MCP** 通过 GitBook API 为 AI 工具提供访问内容和工作流的能力。

当你希望文档读者和终端用户能从已发布文档中找到信息时，请使用已发布文档 MCP。

当你希望团队的代理通过自动化工作流编辑和管理你的文档时，请使用 GitBook MCP。

## 常见问题

<details>

<summary>当我连接 MCP 客户端时，GitBook MCP 支持哪种传输方式？</summary>

GitBook MCP 支持可流式 HTTP。

GitBook MCP 不支持 `stdio` 或 `SSE`.

如果你的客户端要求额外字段，通常可以将它们留空。

</details>

<details>

<summary>当我把客户端连接到 GitBook MCP 时，需要添加 bearer token 吗？</summary>

只有在使用 [个人访问令牌](https://app.gitbook.com/account/developer).

进行身份验证时添加 bearer token。如果你使用 OAuth，不要手动添加 bearer token。你的客户端会在登录流程中获取它。

</details>

<details>

<summary>为什么我把 GitBook MCP 服务器添加到客户端后什么都没发生？</summary>

这在某些 MCP 客户端中是正常的。

添加服务器通常只是保存配置。某些客户端只有在首次连接、列出工具或打开 MCP 面板时才会开始身份验证。

</details>

<details>

<summary>为什么我点击 GitBook MCP 的 Authenticate 后什么都没发生？</summary>

有些客户端会在短暂延迟后打开浏览器登录流程。

在网络缓慢或不稳定时，这个延迟可能更长。

如果大约一分钟后仍未打开浏览器标签页，请检查网络、弹窗设置和默认浏览器。

</details>

<details>

<summary>GitBook MCP 身份验证流程中会发生什么？</summary>

当身份验证成功时，流程通常如下：

1. 客户端连接到 MCP 服务器。
2. 你的浏览器会打开登录流程。
3. 你登录并批准访问。
4. 客户端会显示服务器已连接，或者 MCP 工具变为可用。

</details>

<details>

<summary>我如何判断我的客户端是否已成功通过 GitBook MCP 身份验证？</summary>

具体信号取决于你的客户端，但结果通常很明显。

大多数客户端会移除身份验证提示，显示服务器已连接，或者允许助手列出并调用 MCP 工具。

如果 **Authenticate** 按钮一直显示且没有工具出现，说明登录流程可能尚未完成。

</details>

<details>

<summary>如果 GitBook MCP 身份验证仍然卡住，我应该检查什么？</summary>

尝试以下检查：

* 确认服务器 URL 指向 MCP 端点。
* 确认客户端使用 HTTP 传输。
* 在稳定的网络环境下重试。
* 如果客户端缓存了失败状态，请移除并重新添加服务器。

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/zh/docs-as-code/gitbook-mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
