> 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/getting-started/ai-documentation/gitbook-mcp.md).

# GitBook MCP

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

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

要将你的 AI 编码助手连接到 GitBook 的 MCP，你需要服务器 URL、一种身份验证方式，以及一个受支持的 MCP 客户端。下面的各个部分会逐步引导你完成。

{% hint style="info" %}
需要一个用于已发布文档站点的只读 MCP 服务器吗？GitBook 会自动为你创建一个——参见 [已发布文档的 MCP 服务器](/docs/documentation/zh/ai-yu-sou-suo/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 Code" icon="claude" %}
在终端中注册该服务器：

```bash
claude mcp add --transport http gitbook https://mcp.gitbook.com/mcp
```

然后使用 `claude` 启动 Claude Code，并运行 `/mcp` 完成浏览器登录。

如果你更偏好使用个人访问令牌，请将其作为授权头传入：

```bash
claude mcp add --transport http gitbook https://mcp.gitbook.com/mcp \
  --header "Authorization: Bearer <YOUR_TOKEN>"
```

{% endtab %}

{% tab title="Codex" icon="openai" %}
从终端添加该服务器：

```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/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

{% 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/ai-yu-sou-suo/mcp-servers-for-published-docs.md) 让 AI 工具对已发布内容具有只读访问权限。
* **GitBook MCP** 通过 GitBook API 让 AI 工具访问你的内容和工作流。

当你希望文档读者和最终用户从已发布文档中查找信息时，请使用已发布文档 MCP。&#x20;

当你希望团队的代理通过自动化工作流编辑和管理文档时，请使用 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 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/getting-started/ai-documentation/gitbook-mcp.md?ask=<question>&goal=<endgoal>
```

`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.