> ## 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-TW/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md)。

## v6.3.3 新功能

從 v6.3.3 起，用戶端也可以使用專案歷史記錄：列出變更、比較兩個版本、讀取檔案在某個時間點的內容、儲存和刪除版本，以及還原單一檔案或整個專案。它可以列出追蹤修訂並接受或拒絕，並在你要求時將自己的編輯設為追蹤修訂。它可以對一段文字加上留言、編輯或刪除留言訊息、讀取和傳送專案聊天訊息、移動和重新命名檔案及資料夾、建立資料夾，以及變更拼字檢查語言。誰可以做什麼取決於你在專案中的角色，與編輯器中相同，因為用戶端使用的是你的權杖：請參閱[誰可以做什麼](#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-TW/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-TW/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.