> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理员 Model Context Protocol (MCP) 服务器

> 让 Claude 和 Cursor 等 AI 工具获得对你的 Mintlify 内容和控制台的写入权限，从而编辑页面、更新设置并提交 PR。

<div id="about-the-admin-mcp">
  ## 关于管理员 MCP
</div>

管理员 MCP 服务器赋予 AI 工具对你的 Mintlify 内容和设置的写入权限。可使用它来更新内容并访问你的控制台。借助管理员 MCP，你可以使用你常用的 AI 工具来编辑页面、调整导航结构、更新 `docs.json`、提交拉取请求、修改设置、创建工作流等等。

将任意 MCP 客户端 (例如 Claude、Claude Code 或 Cursor) 连接到管理员 MCP 服务器，即可使用与编写代码相同的工具协同处理你的 Mintlify 内容和设置。使用管理员 MCP 服务器时，所有更改都会发生在某个 branch 上，并需要通过拉取请求合并。

<Note>
  管理员 MCP 服务器允许 AI 工具访问你的 Mintlify 控制台。请将其视为拥有写入权限的同事。仅从受信任的 AI 工具连接它，并在合并前审查每一个拉取请求。
</Note>

<div id="how-the-admin-mcp-differs-from-the-search-mcp">
  ### 管理员 MCP 与搜索 MCP 的区别
</div>

|        | 管理员 MCP                  | 搜索 MCP            |
| :----- | :----------------------- | :---------------- |
| **受众** | 你的团队                     | 你的终端用户            |
| **权限** | 读取、编辑、调整结构、保存、创建工作流、管理设置 | 读取并搜索已发布的页面       |
| **端点** | 由 Mintlify 托管，仅限于你的项目    | 位于你的站点域名上的 `/mcp` |
| **输出** | 内容编辑、导航更改、拉取请求、工作流运行     | 搜索结果和页面内容         |

<div id="connect-to-the-admin-mcp">
  ## 连接到管理员 MCP
</div>

你必须通过 Mintlify 账户完成交互式 OAuth 登录才能连接到管理员 MCP。AI 工具会将该登录会话兑换为限定到单个项目的会话令牌。

<Tabs>
  <Tab title="Claude">
    <Steps>
      <Step title="Add the admin MCP as a custom connector">
        1. 前往 Claude 设置中的 [Connectors](https://claude.ai/settings/connectors) 页面。
        2. 点击 **Add custom connector**。
        3. 添加连接器
           * 名称：Admin MCP
           * URL：`https://mcp.mintlify.com`
        4. 点击 **Add** 并完成 OAuth 登录。
      </Step>

      <Step title="Use the MCP in a chat">
        点击附件按钮 (加号图标)，然后选择你的管理员 MCP 服务器。Claude 现在可以在回答你的提示时调用 Mintlify 管理员 MCP 工具。
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    使用 Claude Code CLI 添加管理员 MCP 服务器：

    ```bash theme={null}
    claude mcp add --transport http mintlify https://mcp.mintlify.com
    ```

    首次使用时，Claude Code 会打开一个浏览器窗口以完成 OAuth 登录。完成认证后，后续调用会复用该会话。
  </Tab>

  <Tab title="Cursor">
    1. 使用 <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (Windows 上为 <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>) 打开命令面板。
    2. 搜索 **Open MCP settings** 并点击 **Add custom MCP**。
    3. 在 `mcp.json` 中添加管理员 MCP：

    ```json theme={null}
    {
      "mcpServers": {
        "mintlify": {
          "url": "https://mcp.mintlify.com"
        }
      }
    }
    ```

    4. 重新加载 Cursor，并在出现提示时完成 OAuth 登录。
  </Tab>
</Tabs>

<div id="how-a-session-works">
  ## 会话的工作方式
</div>

每个管理员 MCP 会话都绑定到单个 Git branch。流程如下：

<Steps>
  <Step title="Check out a branch">
    第一次调用必须是 `checkout`。它会从你的部署 branch 基础上创建一个全新的 `mintlify-mcp/<slug>-<sha>` branch (或附加到你指定的现有 branch)，并返回一个 `editorUrl`，你可以打开它在控制台编辑器中实时跟进。

    如果你需要发现或筛选仓库中现有的 branch，请在 `checkout` 之前调用 `list_branches`。
  </Step>

  <Step title="Read, search, and edit">
    AI 使用 `search`、`read`、`list_nodes`、`edit_page`、`write_page`、`create_node` 和 `update_config` 等工具进行更改。所有编辑都会实时缓冲在会话 branch 上——目前还不会影响你的部署 branch。
  </Step>

  <Step title="Review the diff">
    随时调用 `diff` 查看与 `main` 相比发生了哪些更改。在控制台中打开 `editorUrl`，可以看到相同更改的渲染效果。
  </Step>

  <Step title="Save">
    调用 `save` 将 branch 推送到 Git。使用 `mode: "pr"` (默认值) 创建拉取请求，或使用 `mode: "commit"` 直接推送到现有的 PR branch。
  </Step>

  <Step title="Discard if needed">
    调用 `discard_session` 丢弃所有会话内更改并释放该 branch。
  </Step>
</Steps>

<Tip>
  在活动会话期间再次调用 `checkout` 会将会话切换到新的 branch。可借此放弃进行中的草稿，并在不结束对话的情况下重新开始。
</Tip>

<div id="what-the-admin-mcp-can-do">
  ## 管理员 MCP 可以做什么
</div>

<div id="content">
  ### 内容
</div>

* **`read`** — 获取会话 branch 上任意页面的完整 MDX。
* **`search`** — 在所有页面中查找匹配子字符串或正则表达式的行。
* **`edit_page`** — 对页面进行有针对性的编辑。
* **`write_page`** — 覆盖页面的完整 MDX 内容。

<div id="navigation">
  ### 导航
</div>

* **`list_nodes`** — 遍历导航树，可使用可选筛选条件。按 `parentId` 筛选 (使用 `recursive: true` 包含所有后代)、按一个或多个节点类型筛选，或按任意分区范围筛选：`language`、`version`、`tab`、`dropdown`、`anchor`、`product` 或 `item`。结果通过不透明的 `cursor` 分页。
* **`create_node`** — 添加新的页面、组、tab、anchor、版本、语言、产品或 dropdown。
* **`update_node`** — 就地更新节点属性 (重命名组、更改图标、设置默认版本)。
* **`move_node`** — 移动节点，包括重命名页面的路径。
* **`delete_node`** — 从导航中移除节点。

<div id="configuration">
  ### 配置
</div>

* **`update_config`** — 修改 `docs.json` (主题、导航根节点、集成、SEO 设置)。

<div id="session">
  ### 会话
</div>

* **`checkout`** — 将会话绑定到某个 branch。
* **`list_branches`** — 列出项目可用的 Git branch，可选用 `query` 进行筛选。返回 branch 名称、总数以及部署 branch。在 `checkout` 之前调用此项，可按名称附加到现有 branch。
* **`get_session_state`** — 查看当前 branch、已编辑的文件和待处理的导航差异。
* **`diff`** — 列出会话与 `main` 之间的所有更改。
* **`save`** — 打开拉取请求或提交到会话 branch。
* **`discard_session`** — 丢弃会话及其进行中的更改。

<div id="example-prompts">
  ## 示例提示词
</div>

连接管理员 MCP 后，你可以使用自然语言提示词来驱动它。例如：

* *“检出一个名为 `add-billing-faq` 的 branch，并在 FAQ 组下创建一个名为 'Billing' 的新页面。为这个 Linear 工单中的五个问题草拟答案。”*
* *“找出每一个提到已废弃的 `legacy_token` 字段的页面，并将示例更新为使用 `api_key`。保存为一个标题为 'docs: replace legacy\_token references' 的 PR。”*
* *“重新组织 API 参考：将 webhooks 页面移入名为 'Webhooks' 的新组，并更新图标以与该部分其他内容保持一致。”*

<div id="best-practices">
  ## 最佳实践
</div>

<AccordionGroup>
  <Accordion title="打开编辑器 URL">
    每次 `checkout` 都会返回一个 `editorUrl`。在单独的标签页中打开它，这样你就可以在提示时实时观察 AI 的更改在控制台编辑器中渲染。
  </Accordion>

  <Accordion title="审查每一个 PR">
    管理员 MCP 强大到足以在一次会话中重写数百个页面。在合并之前，请阅读 PR 差异并大致浏览渲染预览。不要对大量更改做盲目通过。
  </Accordion>

  <Accordion title="使用 slug 作为 branch 名称">
    向 `checkout` 传入 `slug` (例如 `add-quickstart`)，使自动生成的 branch 易于阅读。如果不传入，branch 名称会基于会话令牌生成，在你的仓库中很难辨识。
  </Accordion>

  <Accordion title="保持会话聚焦">
    让每个会话专注于一项更改。更小的会话能生成更易审查的拉取请求，并能节省代理的上下文窗口。使用 `discard_session` 后再次 `checkout` 以切换到无关的工作。
  </Accordion>
</AccordionGroup>

<Note>
  会话在 Mintlify 端会持有一个内存中的 branch。如果你在没有保存或丢弃的情况下放弃会话，该 branch 会一直保留到你下一次 checkout 覆盖它为止。请避免在你的仓库中留下陈旧的 `mintlify-mcp/*` branch，并定期清理它们。
</Note>


## Related topics

- [Model Context Protocol (MCP)（模型上下文协议）](/docs/zh/ai/model-context-protocol.md)
- [使用 Devin Desktop 编写文档](/docs/zh/guides/devin-desktop.md)
- [快速入门](/docs/zh/quickstart.md)