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

# MCP 服务器

> 通过 MCP 将 Claude Code 等 AI 客户端连接到项目，检查连接是否正常，并了解客户端能做什么。

每个项目都有自己的 MCP 服务器，因此你电脑上的 AI 客户端可以读取和编辑项目、编译项目并回复其中的评论。客户端使用 Git 身份验证令牌登录。

> [!NOTE]
>
> 如果你看不到 **MCP server** 卡片，请让管理员参阅 [MCP 服务器](https://ayakaleaf-pro.mintlify.site/zh-CN/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md)。

## v6.3.3 新增功能

从 v6.3.3 起，客户端还可以使用项目历史：列出更改、比较两个版本、读取文件在某个时间点的内容、保存和删除版本，以及恢复单个文件或整个项目。它可以列出修订（tracked changes）并接受或拒绝它们，并在你要求时将自己的编辑作为修订。它可以对一段文字添加评论、编辑或删除评论消息、读取和发送项目聊天消息、移动和重命名文件及文件夹、创建文件夹，以及更改拼写检查语言。谁可以做什么取决于你在项目中的角色，与编辑器中相同，因为客户端使用的是你的令牌：请参阅[谁可以做什么](#who-may-do-what)。

MCP 服务器在 v6.3.1 中引入。v6.3.1 和 v6.3.2 拥有相同的 17 个工具；v6.3.3 有 33 个。

| 工具 | v6.3.1 和 v6.3.2 | v6.3.3 |
| - | - | - |
| `get_clone_info`, `get_settings`, `list_files`, `delete_file`, `compile`, `get_compile_log`, `get_output_file_link`, `word_count`, `reply_to_comment`, `resolve_comment`, `reopen_comment` | 是 | 是，无变化 |
| `read_file` | 最新内容 | 还可读取文件在某个 `version` 时的内容 |
| `edit_file`, `write_file` | 遵循项目的修订设置 | 还支持 `trackChanges`，将编辑作为修订 |
| `update_settings` | 编译器、TeX Live 镜像和主文档 | 还包括拼写检查语言 |
| `list_versions` | 版本、注释和日期 | 还包括 `delete_version` 所需的 `id`，以及保存者 |
| `list_comments` | 不带 id 的消息 | 还包括每条消息的 `id`，供 `edit_comment_message` 和 `delete_comment_message` 使用 |
| `list_changes`, `diff`, `create_version`, `delete_version`, `restore_file`, `restore_project`, `list_tracked_changes`, `accept_tracked_changes`, `reject_tracked_changes`, `add_comment`, `edit_comment_message`, `delete_comment_message`, `list_chat_messages`, `send_chat_message`, `move_file`, `create_folder` | 否 | 是 |

## 连接客户端

**1. 打开对话框**

打开项目。在左侧栏中，点击 **Integrations**，然后点击 **MCP server**。

![带有 MCP server 卡片的 Integrations 面板](https://mintcdn.com/ayakaleaf-pro/IsGnx0wnzqtV4hI8/images/on-premises/mcp-server-integrations.png?fit=max\&auto=format\&n=IsGnx0wnzqtV4hI8\&q=85\&s=c38ad3def0079dc27b1774c7e0487482)

Integrations 面板

对话框会显示此项目服务器的地址，并为每个客户端提供一个标签页：**Claude Code**、**Codex**、**Cursor**、**VS Code** 和 **Gemini CLI**。

![MCP server 对话框，包含地址、每个客户端的标签页以及 Claude Code 的命令](https://mintcdn.com/ayakaleaf-pro/IsGnx0wnzqtV4hI8/images/on-premises/mcp-server-dialog.png?fit=max\&auto=format\&n=IsGnx0wnzqtV4hI8\&q=85\&s=e8554732779d9c6c7fb0cf0240364ce5)

MCP server 对话框

**2. 创建令牌**

点击 **Go to settings**。你的账号设置会在新标签页中打开。在 **Git integration** 下，点击 **Generate token**；如果你已有令牌，则点击 **Add another token**。点击 **Copy** 并将令牌妥善保存，因为它只会显示一次。然后点击 **Close**。

![带有 Copy 按钮的 Git authentication token 对话框](https://mintcdn.com/ayakaleaf-pro/IsGnx0wnzqtV4hI8/images/on-premises/mcp-server-token.png?fit=max\&auto=format\&n=IsGnx0wnzqtV4hI8\&q=85\&s=f4661b468dd1d409ef19967216955ae4)

你的新令牌

你已用于 [Git 集成](https://ayakaleaf-pro.mintlify.site/zh-CN/on-premises/user-guide/users/git-integration.md)的令牌同样可用，并且一个令牌可以用于你的所有项目。

**3. 将服务器添加到客户端**

回到对话框，点击你的客户端对应的标签页，然后点击配置旁边的 **Copy**。

| 标签页 | 放在哪里 | 令牌 |
| - | - | - |
| **Claude Code** | 在终端中运行该命令 | 替换命令中的 `<token>` |
| **Codex** | `~/.codex/config.toml` | 放入环境变量 `OVERLEAF_TOKEN` |
| **Cursor** | `~/.cursor/mcp.json` | 放入环境变量 `OVERLEAF_TOKEN` |
| **VS Code** | `.vscode/mcp.json` | 该文件使用名为 `overleaf-token` 的密码提示代替令牌 |
| **Gemini CLI** | 在终端中运行该命令 | 替换命令中的 `<token>` |

该地址只属于一个项目。要连接另一个项目，请以另一个名称添加它，因为 `overleaf` 已被占用。例如，对于 Claude Code，将命令中的 `overleaf` 改为 `overleaf-lab`。

## 检查连接

### 使用 Claude Code

```bash theme={null}
claude mcp list
```

服务器显示为已连接：

```text theme={null}
overleaf: https://<your-site>/project/<project-id>/mcp (HTTP) - ✔ Connected
```

### 使用 curl

无论使用哪种客户端，此方法都适用。替换地址和令牌，然后发送 MCP 协议的 `initialize` 请求：

```bash theme={null}
curl -X POST https://<your-site>/project/<project-id>/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```

响应中会给出服务器名称，后面是它给客户端的说明：

```json theme={null}
{"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":true}},"serverInfo":{"name":"overleaf","version":"1.0.0"},"instructions":"This server works on one Overleaf project. ..."},"jsonrpc":"2.0","id":1}
```

要查看工具，请使用相同的命令发送 `tools/list`。响应会列出 33 个工具；如果你的站点关闭了项目聊天，则为 31 个。v6.3.3 之前会列出 17 个。

```bash theme={null}
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

要调用某个工具，请发送 `tools/call`：

```bash theme={null}
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_files","arguments":{}}}'
```

```json theme={null}
{"result":{"content":[{"type":"text","text":"[\n  {\n    \"path\": \"main.tex\",\n    \"type\": \"doc\"\n  }\n]"}]},"jsonrpc":"2.0","id":3}
```

### 在账号设置中

在 **Git integration** 下，**Last used** 会显示服务器收到某个令牌的日期。

![令牌列表，第一个令牌的 Last used 下有日期，第二个为 N/A](https://mintcdn.com/ayakaleaf-pro/IsGnx0wnzqtV4hI8/images/on-premises/mcp-server-last-used.png?fit=max\&auto=format\&n=IsGnx0wnzqtV4hI8\&q=85\&s=2abe32cb469d17b8b8c5eb18f1c0c2d3)

第一个令牌已被使用

### 如果无法连接

| 你看到的内容 | 含义 |
| - | - |
| 状态 `401`，或在 Claude Code 中显示 `✘ Failed to connect` 和 `HTTP 401` | 令牌缺失、错误或已删除 |
| 状态 `404` | 没有此 ID 的项目 |
| 状态 `405` | 请求不是 `POST` |
| 状态 `406` 并显示 `Not Acceptable` | 缺少 `Accept` 标头：客户端必须同时接受 `application/json` 和 `text/event-stream` |

## 客户端工作时你会看到什么

客户端所做的编辑会像协作者的编辑一样实时显示在打开的编辑器中，无需重新加载。新文件和文件夹、移动和重命名会显示在文件树中。

![编辑器显示 edit\_file 添加的一行，没有对话框，也无需重新加载](https://mintcdn.com/ayakaleaf-pro/IsGnx0wnzqtV4hI8/images/on-premises/mcp-server-live-edit.png?fit=max\&auto=format\&n=IsGnx0wnzqtV4hI8\&q=85\&s=51163f1de5bec88d50bd96089bd1a9a2)

edit\_file 添加的一行

`edit_file` 只会更改恰好出现一次的文本。否则客户端会收到错误，例如 `oldString not found in main.tex, read_file again` 或 `oldString appears 2 times in main.tex, add context`，且不会做任何更改。

从 v6.3.3 起，`move_file` 可以移动或重命名文件或文件夹，并按需创建新路径中的文件夹；`create_folder` 可以创建文件夹。如果找不到文件或新路径已存在，客户端会收到错误，且不会做任何更改。`update_settings` 还可以更改拼写检查语言（例如改为 `de`），或关闭拼写检查。

评论的回复会以你的名义显示在审阅面板中，因为令牌是你的。通过服务器解决的评论会从面板中移除，重新打开后会再次出现。

![审阅面板中的一条评论，附有 reply\_to\_comment 发送的回复](https://mintcdn.com/ayakaleaf-pro/IsGnx0wnzqtV4hI8/images/on-premises/mcp-server-comment.png?fit=max\&auto=format\&n=IsGnx0wnzqtV4hI8\&q=85\&s=7b5cd74110b014b389bae7209b1330f0)

reply\_to\_comment 发送的回复

从 v6.3.3 起，`add_comment` 可以对一段文字添加评论。该文字必须在文件中恰好出现一次；如果出现多次，客户端还会提供一段包含它、且只出现一次的更长文字，而评论只会添加到该文字上。评论会以你的名义显示在审阅面板中，并在文件变化时始终附着在其文字上。`edit_comment_message` 可以修改你自己的一条消息。`delete_comment_message` 可以删除一条消息；删除第一条消息会删除整条评论，与审阅面板中相同。

`compile` 会编译项目并返回输出文件列表。随后，`get_output_file_link` 会给出下载 PDF 或其他输出文件的链接。该链接无需令牌，并在 5 分钟后失效。

完整的工具列表请参阅 [Tools](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md#tools)。

## 修订

从 v6.3.3 起，你可以要求客户端将其编辑作为修订，例如 *Rewrite the abstract as a tracked change*。这样，`edit_file` 和 `write_file` 对现有文件的更改会以你的名义成为修订，即使项目中的修订功能处于关闭状态，你也可以在审阅面板中接受或拒绝它。新文件永远不会成为修订。如果你没有提出要求，编辑会遵循项目的修订设置，与你在编辑器中的编辑相同：当修订对你或对所有人开启时，编辑会被追踪。

如果项目所有者的账号没有修订功能，客户端会收到 `Track changes is off for this project`，且不会做任何更改。

要审阅客户端的每一次编辑，请为自己开启修订。要在审阅面板中区分它的编辑和你的编辑，请为客户端提供另一个与你共享该项目的账号的令牌。

`list_tracked_changes` 会列出修订及其文件、插入或删除的文本、作者和时间。`accept_tracked_changes` 和 `reject_tracked_changes` 接受修订的 id，其作用与审阅面板相同：被接受的更改保留在文本中，被拒绝的插入会被移除，被拒绝的删除会恢复。打开的编辑器无需重新加载即可显示结果。这些工具会告诉客户端只接受或拒绝你要求的更改。

## 历史

从 v6.3.3 起，客户端看到的项目历史与历史面板中显示的相同。

| 工具 | 作用 |
| - | - |
| `list_changes` | 列出更改，最新的在前：谁在何时更改了哪些文件，以及每次更改前后的版本。较早的更改会分批返回。 |
| `diff` | 比较两个版本：单个文件以统一差异格式显示（类似 `git diff`），或列出被添加、删除、编辑或重命名的文件 |
| 带 `version` 的 `read_file` | 读取文件在某个版本时的内容 |
| `list_versions` | 列出已保存的版本，以及它们的注释和保存者 |
| `create_version` | 保存最新版本或较早的版本并附上注释，类似 **Label this version** |
| `delete_version` | 删除已保存的版本；其中的更改会保留 |
| `restore_file` | 将文件恢复到某个版本时的状态，类似 **Restore this version** |
| `restore_project` | 将整个项目恢复到某个版本时的状态，类似 **Restore project to this version** |

恢复本身就是一次新的更改，因此你可以用同样的方式撤销它。这些工具会告诉客户端只在你要求时才进行恢复。

如果项目所有者没有完整的项目历史，客户端只能看到最近 24 小时内的更改（如果所有更改都更早，则只能看到最新的一次），与历史面板中相同。它无法比较、读取或恢复更早的版本。

## 项目聊天

从 v6.3.3 起，`list_chat_messages` 会读取项目聊天，最新的在前，每次 50 条消息。`send_chat_message` 会以你的名义发送消息，该消息会立即显示在打开的聊天中。如果你的站点关闭了项目聊天，客户端将没有这两个工具。

## 谁可以做什么

客户端可以做你在项目中的角色所允许的事情。

| 客户端执行的操作 | 所有者 | 编辑者 | 审阅者 | 查看者（指定的协作者） | 查看者（链接共享） |
| - | -: | -: | -: | -: | -: |
| 读取文件和设置、编译、读取日志、下载 PDF | 是 | 是 | 是 | 是 | 是 |
| 写入、编辑、移动和删除文件，创建文件夹，更改设置 | 是 | 是 | 否 | 否 | 否 |
| 查看历史、评论和修订 | 是 | 是 | 是 | 是 | 否 |
| 读取和发送聊天消息 | 是 | 是 | 是 | 是 | 否 |
| 添加评论并回复评论 | 是 | 是 | 是 | 否 | 否 |
| 解决、重新打开或删除评论 | 是 | 是 | 自己发起的评论 | 否 | 否 |
| 编辑评论消息 | 自己的 | 自己的 | 自己的 | 否 | 否 |
| 删除评论消息 | 是 | 是 | 自己的 | 否 | 否 |
| 接受或拒绝修订 | 是 | 是 | 否 | 否 | 否 |
| 保存版本 | 是 | 是 | 是 | 否 | 否 |
| 删除已保存的版本 | 是 | 自己保存的版本 | 自己保存的版本 | 否 | 否 |
| 恢复文件或项目 | 是 | 是 | 否 | 否 | 否 |

通过链接加入的编辑者视为编辑者。审阅者无法通过 MCP 编辑文件，即使作为修订也不行。

## 断开客户端

删除令牌：请参阅[删除令牌](https://ayakaleaf-pro.mintlify.site/zh-CN/on-premises/user-guide/users/git-integration.md#delete-a-token)。此后，服务器会对该令牌返回 `401`。如果你也将它用于 Git，Git 也将不再接受它。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.