> 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/ai-for-your-readers/mcp-servers-for-published-docs.md).

# 已发布文档的 MCP 服务器

发布在 GitBook 上的文档会自动生成一个 MCP 服务器，你可以将其连接到外部工具

每个已发布的 GitBook 站点都会自动包含一个模型上下文协议 (MCP) 服务器。

AI 工具可以通过它直接读取你已发布的文档。它适用于 Claude、Claude Code、Cursor、Codex、VS Code 以及其他 MCP 客户端。

### 选择正确的端点 <a href="#choose-the-right-endpoint" id="choose-the-right-endpoint"></a>

你的 MCP 服务器位于已发布的站点 URL 后面，使用以下其中一个端点：

| 如果你的站点是……                                 | 使用此 URL                             | 示例                                           |
| ----------------------------------------- | ----------------------------------- | -------------------------------------------- |
| 公开站点、通过分享链接共享且所有已发布内容均可查看的站点，或完全需要身份验证的站点 | `{docs-site-url}/~gitbook/mcp`      | `https://gitbook.com/docs/~gitbook/mcp`      |
| 部分需要身份验证，仍有一些公开内容或通过分享链接可访问的内容            | `{docs-site-url}/~gitbook/mcp/auth` | `https://gitbook.com/docs/~gitbook/mcp/auth` |

对于完全需要身份验证的站点，客户端会通过 MCP 发现和 OAuth 登录。详情请参阅 [MCP 授权流程](https://modelcontextprotocol.io/docs/tutorials/security/authorization#the-authorization-flow-step-by-step).

{% hint style="info" %}
如果在浏览器中打开此 URL，你会看到错误。请在能够发送 HTTP 请求的工具中使用它，例如 AI 助手或 IDE。
{% endhint %}

{% hint style="info" %}
**使用 MCP 服务器连接** 必须位于 **已启用的操作** 列表中 **站点自定义** → **页面操作** 才能使 MCP 服务器正常运行。如果将其移至 **可用操作**，或关闭 **页面操作**, `~gitbook/mcp` 会返回 `404`.
{% endhint %}

### 连接 AI 工具

{% stepper %}
{% step %}

#### 查找 MCP 服务器 URL

从已发布的文档 URL 开始，然后添加 [选择正确的端点](#choose-the-right-endpoint).

例如，如果你的文档站点是 `https://gitbook.com/docs`，那么你的 MCP 服务器 URL 是 `https://gitbook.com/docs/~gitbook/mcp`.
{% endstep %}

{% step %}

#### 将服务器添加到你的工具

使用下方对应工具的选项卡。将 `{docs-site-url}` 替换为你自己的已发布站点 URL。

如果你的站点使用第二个端点，请将 `/~gitbook/mcp` 替换为 `/~gitbook/mcp/auth`.
{% endstep %}

{% step %}

#### 提出测试问题

运行 [试试看](#try-it)中的任意一个提示。如果工具能够搜索你的文档并根据文档内容作答，说明连接正常。
{% endstep %}
{% endstepper %}

{% tabs %}
{% tab title="Claude" %}
这些步骤适用于网页版 Claude 和 Claude Desktop。

打开 **设置** → **连接器**.

点击 **添加自定义连接器**。然后粘贴 MCP 服务器 URL，例如 `{docs-site-url}/~gitbook/mcp`.

示例：

```
https://gitbook.com/docs/~gitbook/mcp
```

如果 Claude 未显示远程连接器，可能是你当前的套餐或功能发布阶段尚不支持此功能。
{% endtab %}

{% tab title="Claude Code" %}
在终端中运行此命令：

```shell
claude mcp add --transport http my-docs https://gitbook.com/docs/~gitbook/mcp
```

将 `my-docs` 替换为你想要的任意服务器名称。

如果你的网站使用经过身份验证的公共端点，请将 URL 后缀替换为 `/~gitbook/mcp/auth`.
{% endtab %}

{% tab title="Cursor" %}
打开 **设置** → **MCP**.

点击 **添加新的 MCP 服务器**。然后粘贴 `{docs-site-url}/~gitbook/mcp`.

你也可以将此文件添加到 `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "my-docs": {
      "url": "https://gitbook.com/docs/~gitbook/mcp"
    }
  }
}
```

将 `my-docs` 替换为你自己的服务器名称（如有需要）。
{% endtab %}

{% tab title="Codex" %}
使用 `codex mcp add` 命令，或将服务器添加到你的 `config.toml`.

命令示例：

```shell
codex mcp add my-docs https://gitbook.com/docs/~gitbook/mcp
```

配置示例：

```toml
[mcp_servers.my-docs]
url = "https://gitbook.com/docs/~gitbook/mcp"
```

将 `my-docs` 替换为你自己的服务器名称（如有需要）。
{% endtab %}

{% tab title="VS Code（Copilot）" %}
打开你的 `mcp.json` 文件。然后添加一个使用 HTTP 传输的服务器条目：

```json
{
  "servers": {
    "my-docs": {
      "type": "http",
      "url": "https://gitbook.com/docs/~gitbook/mcp"
    }
  }
}
```

将 `my-docs` 替换为你自己的服务器名称（如有需要）。
{% endtab %}
{% endtabs %}

### 试试看 <a href="#try-it" id="try-it"></a>

将以下任一提示词粘贴到你的助手中：

* `Using the my-docs MCP server, how do I set up authenticated access?`
* `Search my docs for everything about custom domains and summarize the steps.`
* `List the tools exposed by the my-docs MCP server. Then use them to find the page about page actions.`

如果你使用智能体工具，也可以向它提供以下设置提示词：

```
添加一个名为 my-docs、使用 HTTP 传输的 MCP 服务器，地址为 https://gitbook.com/docs/~gitbook/mcp。然后列出其可用工具，以验证连接是否成功。
```

### 要求

使用 MCP 服务器需要：

* 您的网站必须已发布。MCP 服务器仅提供已发布的内容。
* **通过 MCP 访问你的文档** 必须在你的网站的 **扩展 → MCP 访问**.
* **使用 MCP 服务器连接** 必须位于 **已启用的操作** 列表中，在 **站点自定义** → **页面操作**.
* 您的工具必须支持通过 HTTP 使用 MCP。
* 如果您的网站使用 [身份验证访问](https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access.md)，您的工具必须支持 [MCP 授权规范](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization).
* 如果您的网站使用分享链接，请使用分享链接对应的网站 URL，然后添加以下位置提供的端点： [选择正确的端点](#choose-the-right-endpoint).
* GitBook 仅支持 HTTP 传输。 `stdio` 和 `SSE` 均不受支持。

### 启用 MCP 服务器

打开你的网站的 **扩展 → MCP 访问** 并开启 **通过 MCP 访问你的文档**。此页面还会显示你的网站的 **MCP 端点** 和 **经过身份验证的 MCP 端点**.

然后，在 [站点自定义](https://gitbook.com/docs/documentation/zh/manage-your-site/customization.md)中，打开 [页面操作](https://gitbook.com/docs/documentation/zh/manage-your-site/customization/extra-configuration.md#page-actions)。确保 **页面操作** 已启用。如果 **连接 MCP 服务器** 位于 **可用操作**，将其拖到 **已启用的操作**.

这样会启用站点的 MCP 服务器，并在页面操作菜单中添加一个可复制的 MCP 链接。服务器和链接是配套的：如果将 **使用 MCP 服务器连接** 移回 **可用操作** 以隐藏链接，GitBook 也会关闭 MCP 服务器。

### 使用限制

目前，所有套餐均可使用已发布文档的 MCP 服务器，实际上没有调用次数限制。

此 `askQuestion` 工具会使用你网站的 AI，因此只有在网站启用了 AI 时才能使用。如果组织的 AI 暂停，该工具也会停止工作，例如 AI 积分用尽时。搜索和阅读页面仍可正常使用。

### 隐私与访问权限

使用 [选择正确的端点](#choose-the-right-endpoint).

MCP 服务器提供对已发布文档的只读访问权限。

隐藏的页面仍可通过 MCP 访问。隐藏页面只会将其从已发布的目录中移除。

它不会公开账户数据、分析数据或 GitBook 内部数据。

它仅提供最新的已发布版本。草稿和未发布的更改仍为私密内容。

### 故障排除

如果工具无法连接：

* 确认已发布的网站可以访问。
* 确认 URL 使用的端点来自 [选择正确的端点](#choose-the-right-endpoint).
* 如果网站使用身份验证，请使用支持 [MCP 授权规范](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization).
* 如果工具需要 `stdio` 或 `SSE`，因此无法与 GitBook 配合使用。

### 在需要身份验证的网站上使用 MCP

如果你的 GitBook 网站使用 [身份验证访问](https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access.md)，那么位于 `/~gitbook/mcp` 的 MCP 服务器会使用相同的身份验证。支持 [MCP 授权规范](https://modelcontextprotocol.io/docs/tutorials/security/authorization) 的 MCP 客户端（包括 Claude 和 Claude Code）可以通过 OAuth 和动态客户端注册（DCR）自动连接。

如果你的网站使用的是分享链接，请使用完整的分享链接网站 URL，然后添加以下部分中的端点： [选择合适的端点](#choose-the-right-endpoint).

GitBook 不支持仅通过分享链接访问的网站，也不支持使用请求静态标头传递访客身份验证令牌的网站进行 MCP 身份验证。

受支持的 MCP 客户端（包括 Claude）会遵循 [MCP 授权规范](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) 进行连接。

{% stepper %}
{% step %}

#### 发现 OAuth 服务器

在 MCP 握手期间，客户端会发现你网站的 OAuth 服务器。
{% endstep %}

{% step %}

#### 使用 DCR 注册客户端

客户端通过动态客户端注册来注册 OAuth 客户端。

你无需手动创建客户端 ID。
{% endstep %}

{% step %}

#### 通过网站的身份验证提供商登录

客户端会将你重定向到网站的身份验证提供商。

使用文档网站已在使用的同一身份验证提供商登录。
{% endstep %}

{% step %}

#### 用授权码换取令牌

登录后，客户端会用授权码换取访问令牌。
{% endstep %}

{% step %}

#### 重复使用令牌

客户端会在令牌过期前，在后续的 MCP 请求中携带该令牌。
{% endstep %}
{% endstepper %}

此流程适用于以下需要身份验证的访问后端：

* [Auth0](https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access/setting-up-auth0.md)
* [Azure AD](https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access/setting-up-azure-ad.md)
* [Okta](https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access/setting-up-okta.md)
* [AWS Cognito](https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access/setting-up-aws-cognito.md)
* [OIDC](https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access/setting-up-oidc.md)
* [自定义后端](https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access/setting-up-a-custom-backend.md) 并配置了备用 URL

{% hint style="warning" %}
MCP 身份验证不支持仅依赖在请求标头中使用静态访客身份验证令牌的网站。

请改用上述需要身份验证的访问后端之一。
{% endhint %}

要完成设置，请先阅读 [身份验证访问](https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access.md) 和 [启用身份验证访问](https://gitbook.com/docs/documentation/zh/publish/site-audience/authenticated-access/enabling-authenticated-access.md).


---

# 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/ai-for-your-readers/mcp-servers-for-published-docs.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.
