内容
# 🍃 Overleaf MCP 服务器
最全面的 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器，适用于 [Overleaf](https://www.overleaf.com)。
**18 种工具**，涵盖完整的 CRUD 操作、LaTeX 结构分析、git 历史记录和差异、PDF 编译和下载 — 所有操作均可通过 AI 助手完成。
**简单设置** — 在注册 MCP 服务器时，设置两个环境变量 (`OVERLEAF_SESSION`，可选 `OVERLEAF_GIT_TOKEN`)，即可完成设置。
```
你: "列出我的项目"
AI: [list_projects] 你有 5 个项目。哪一个？
你: "读取我的论文中的 main.tex"
AI: [read_file] 内容如下：…
你: "重写摘要，使其更简洁"
AI: [edit_file] ✓ 已编辑并推送
你: "编译并下载 PDF"
AI: [compile_project + download_pdf] PDF 已保存到 ~/Desktop/thesis.pdf ✓
```
> 注意：早期版本包含一个 `overleaf_setup` / `overleaf_save_credentials` 向导。这些工具已删除 — 现在直接从环境变量中读取凭证。
---
## 🆚 与其他 Overleaf MCP 服务器比较
| 功能 | **本项目** | tamirsida | GhoshSrinjoy | anu2711 | Junfei-Z | mjyoo2 |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| **语言** | Python | Python | JS | Python | JS | JS |
| **认证** | Git + Cookie | Git | Git | Cookie | Git | Git |
| list_projects | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| list_files | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| read_file | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| get_sections | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
| get_section_content | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
| **create_file** | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
| **create_project** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **edit_file** (精确) | ✅ | ✅ | ✅* | ✅ | ✅* | ❌ |
| **rewrite_file** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| **update_section** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **delete_file** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| **list_history** | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| **get_diff** | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| **compile_project** | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
| **download_pdf** | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
| **download_log** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| sync_project | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| status_summary | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ |
| 多项目支持 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 线程安全锁定 | ✅ | ❌ | ✅ (Redis) | ❌ | ❌ | ❌ |
| Docker 支持 | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| 免费 Overleaf 层级 | ✅† | ❌ | ❌ | ✅ | ❌ | ❌ |
| **总工具数** | **18** | 12 | 9 | 6 | 8 | 6 |
\* 仅支持完整的文件重写，不支持精确的旧→新替换。
† 编译/下载工具在免费层级上通过会话 cookie 工作；基于 Git 的工具需要 Git 集成。
---
## ✨ 主要优势
- **18 种工具** — 所有 Overleaf MCP 服务器中最多的工具
- **零配置** — 只需两个环境变量，无需配置文件或项目设置
- **双重认证** — Git 令牌用于读写 + 会话 cookie 用于编译/下载
- **精确编辑** — `edit_file` 执行精确的搜索和替换（类似 `sed`），而非完整重写
- **LaTeX 感知** — 章节层次结构解析，带有缩进预览
- **Git 历史记录和差异** — 审查更改，比较版本，按文件/日期筛选
- **编译** — 触发构建并下载 PDF，无需离开 AI 聊天
- **编译日志** — `download_log` 用于调试 LaTeX 错误
- **线程安全** — 按项目锁定，防止并发 Git 损坏
- **干净的 Python** — 模块化架构，类型提示，异步编程
---
## 📦 安装
### 选项 1：pip（推荐）
该软件包已在 PyPI 上发布为 **`overleaf-mcp-plus`** （普通的 `overleaf-mcp` 名称被无关项目占用）。CLI 入口点仍为 `overleaf-mcp`。
```bash
# 核心（仅基于 Git 的工具）
pip install overleaf-mcp-plus
# 带有编译/下载支持（推荐）
pip install "overleaf-mcp-plus[compile]"
```
或通过 `uvx` 直接运行，无需安装：
```bash
uvx --from "overleaf-mcp-plus[compile]" overleaf-mcp
```
### 选项 2：从源代码
```bash
git clone https://github.com/rangehow/overleaf-mcp.git
cd overleaf-mcp
pip install -e .
# 或使用 uv
uv venv && uv pip install -e .
```
### 选项 3：Docker
```bash
git clone https://github.com/rangehow/overleaf-mcp.git
cd overleaf-mcp
docker compose build
```
---
## 🔧 设置
通过环境变量配置凭证。有两种凭证适用于两组不同的功能 — 您可以提供其中一种或两种。
### 步骤 1 — 获取会话 cookie（必需）
`overleaf_session2` cookie 是 **HttpOnly**，因此只能从浏览器的开发者工具面板中读取（不能从 JavaScript / 控制台中读取）。
1. 登录 <https://www.overleaf.com>。
2. 按 <kbd>F12</kbd> → **应用程序** 选项卡（Firefox：*存储*；Safari：*存储*）。
3. 展开 **Cookies → https://www.overleaf.com**。
4. 复制名为 `overleaf_session2` 的行的 **值**。它以 `s%3A…` 开头。
### 步骤 2 — 获取 Git 令牌（可选，用于编辑工具）
1. 打开 <https://www.overleaf.com/user/settings>。
2. 滚动到 **Git 集成 → 创建令牌**。
3. 复制令牌（它以 `olp_` 开头；仅显示一次）。
### 步骤 3 — 将它们传递给服务器
将您的 MCP 客户端指向 `overleaf-mcp` 并提供环境变量。在 Claude Desktop / Claude Code 中（`claude_desktop_config.json` 或 `.mcp.json`）：
```json
{
"mcpServers": {
"overleaf": {
"command": "overleaf-mcp",
"env": {
"OVERLEAF_SESSION": "s%3A...",
"OVERLEAF_GIT_TOKEN": "olp_..."
}
}
}
}
```
在 chatui 的 MCP 目录中，**Overleaf** 卡在安装时提示这两个字段 — 无需 shell 设置。
### 两种凭证，不同用途
| 凭证 | 可以执行的操作 | 何时需要 |
|---|---|---|
| **会话 cookie** (`overleaf_session2`) | `list_projects`，编译，下载 PDF，下载日志，创建项目 | 适用于免费层级。过期约 30 天 — 当工具开始因身份验证错误而失败时，请刷新。 |
| **Git 令牌** (`olp_...`) | 读取/编辑文件，提交历史，差异 | 可选。仅当您要编辑文件时需要。需要付费计划。 |
您可以先使用会话 cookie，然后再添加 Git 令牌。
### 所有环境变量
| 变量 | 描述 |
|---|---|
| `OVERLEAF_SESSION` | 会话 cookie。 `list_projects` / 编译 / pdf / 创建项目所需。 |
| `OVERLEAF_GIT_TOKEN` | Git 令牌。 `read` / `edit` / 历史记录 / 差异工具所需。 |
| `OVERLEAF_BASE_URL` | Overleaf URL（默认：`https://www.overleaf.com`） |
| `OVERLEAF_GIT_HOST` | Git 主机（默认：`git.overleaf.com`） |
| `OVERLEAF_TEMP_DIR` | 本地 Git 缓存（默认：`./overleaf_cache`） |
| `OVERLEAF_GIT_AUTHOR_NAME` | Git 作者姓名（默认：`Overleaf MCP`） |
| `OVERLEAF_GIT_AUTHOR_EMAIL` | Git 作者邮箱（默认：`mcp@overleaf.local`） |
| `HISTORY_LIMIT_DEFAULT` | 默认提交限制（默认：`20`） |
| `HISTORY_LIMIT_MAX` | 最大提交限制（默认：`200`） |
| `DIFF_CONTEXT_LINES` | 差异上下文行数（默认：`3`） |
| `DIFF_MAX_OUTPUT_CHARS` | 最大差异大小（默认：`120000`） |
---
## 🔌 客户端设置
### Docker
```json
{
"mcpServers": {
"overleaf": {
"command": "docker",
"args": ["compose", "run", "--rm", "-T", "mcp"],
"cwd": "/path/to/overleaf-mcp",
"env": {
"OVERLEAF_SESSION": "s%3A...",
"OVERLEAF_GIT_TOKEN": "olp_..."
}
}
}
}
```
（有关 Claude Desktop / Claude Code，请参见上面的设置部分。）
---
## 🛠️ 工具参考
### 创建
| 工具 | 描述 |
|---|---|
| `create_file` | 创建新文件（自动创建文件夹），提交并推送 |
| `create_project` | 创建新的空白 Overleaf 项目（需要会话 cookie） |
### 读取
| 工具 | 描述 |
|---|---|
| `list_projects` | 列出 Overleaf 账户中的所有项目 |
| `list_files` | 列出文件，可选按扩展名过滤 |
| `read_file` | 读取文件内容 |
| `get_sections` | 解析 LaTeX 章节层次结构并预览 |
| `get_section_content` | 获取章节的完整内容 |
| `list_history` | Git 提交历史记录（带有日期/文件/限制过滤器） |
| `get_diff` | Git 差异比较 refs 或工作树 |
| `status_summary` | 项目概述：文件数，结构，状态 |
### 更新
| 工具 | 描述 |
|---|---|
| `edit_file` | 精确搜索和替换（必须精确匹配一次） |
| `rewrite_file` | 替换整个文件内容 |
| `update_section` | 按标题更新 LaTeX 章节内容 |
| `sync_project` | 从 Overleaf 拉取最新更改 |
### 删除
| 工具 | 描述 |
|---|---|
| `delete_file` | 删除文件，提交并推送 |
### 编译和 PDF
| 工具 | 描述 |
|---|---|
| `compile_project` | 在 Overleaf 上触发 PDF 编译 |
| `download_pdf` | 下载编译后的 PDF 到本地路径 |
| `download_log` | 下载编译日志用于调试 |
---
## 💡 使用示例
```
"列出我的项目"
"列出项目 64a1b2c3d4e5f6a7b8c9d0e1 中的所有文件"
"读取 main.tex"
"显示 chapter1.tex 中的章节"
"获取介绍部分的內容"
"修复错误：将 'teh' 更改为 'the' in main.tex"
"用以下内容重写摘要：[新内容]"
"用以下内容更新方法部分：[新内容]"
"创建一个名为 references.bib 的新文件，内容为：[内容]"
"删除旧的 appendix.tex 文件"
"显示最后 5 次提交"
"自上周以来，main.tex 文件发生了什么变化？"
"显示 HEAD~3 和 HEAD 之间的差异"
"编译我的论文并告诉我是否成功"
"将 PDF 下载到 ~/Desktop/thesis.pdf"
"显示编译日志 — 我有一个错误"
```
---
## 🏗️ 架构
```
┌─────────────────┐ MCP（stdio） ┌──────────────────────────┐
│ AI 助手 │◄─────────────►│ overleaf-mcp 服务器 │
│ （Claude 等） │ │ │
└─────────────────┘ │ ┌────────────────────┐ │
│ │ Git 客户端 │ │── Git HTTPS ──► git.overleaf.com
│ │ （clone/pull/push）│ │
│ └────────────────────┘ │
│ ┌────────────────────┐ │
│ │ LaTeX 解析器 │ │
│ │ （sections/struct）│ │
│ └────────────────────┘ │
│ ┌────────────────────┐ │
│ │ 编译模块 │ │── HTTPS ──► www.overleaf.com
│ │ （PDF/日志下载） │ │
│ └────────────────────┘ │
└──────────────────────────┘
```
**模块：**
- `credentials.py` — 从环境变量读取会话 cookie + Git 令牌
- `config.py` — 项目配置 + Overleaf 端点
- `git_client.py` — Git 操作（clone/pull/push/diff/history）
- `latex.py` — LaTeX 文档结构解析
- `compile.py` — PDF 编译和下载（使用会话 cookie）
- `server.py` — 带有 18 种工具定义的 MCP 服务器
---
## 🪪 本地复制元数据侧车
每次 `download_source` 提取项目到本地目录，或 `ensure_repo` 克隆到 Git 缓存中，服务器都会在该副本的根目录下生成一个小的 `.overleaf-project.json` 文件：
```json
{
"project_id": "69e46cd469c0fc49d2627320",
"name": "[阿布] 毕业论文魔改版",
"overleaf_url": "https://www.overleaf.com/project/69e46cd469c0fc49d2627320",
"source": "zip",
"downloaded_at": "2026-04-22T10:54:55+00:00"
}
```
这让任何工具（包括 AI 助手）都能明确识别本地工作目录对应哪个 Overleaf 项目 — 不再需要根据文件名进行猜测。对于 Git 支持的副本，该文件被添加到 `.git/info/exclude`，因此它永远不会被推送回 Overleaf。
## 🔒 安全
- 凭证仅从环境变量读取 — 服务器不会将任何内容持久化到磁盘
- 所有文件操作上的路径遍历保护
- 按项目锁定，防止并发 Git 损坏
- 会话 cookie 过期作为明确的身份验证错误显示，提示用户刷新 `OVERLEAF_SESSION`
---
## 🐳 自托管 Overleaf
适用于自托管 Overleaf 实例：
```bash
export OVERLEAF_BASE_URL="https://your-overleaf.example.com"
export OVERLEAF_GIT_HOST="your-overleaf.example.com"
```
---
## 📄 许可证
MIT 许可证 — 有关详细信息，请参见 [LICENSE](LICENSE)。
---
## 🙏 致谢
灵感来自并建立在以下想法之上：
- [tamirsida/overleaf_mcp](https://github.com/tamirSida/overleaf_MCP) — 完整的 CRUD Python 服务器
- [GhoshSrinjoy/Overleaf-mcp](https://github.com/GhoshSrinjoy/Overleaf-mcp) — Redis 队列，历史记录/差异
- [anu2711/overleaf-mcp](https://github.com/anu2711/overleaf-mcp) — 通过会话 cookie 编译/下载
- [mjyoo2/OverleafMCP](https://github.com/mjyoo2/OverleafMCP) — 原始只读 MCP（103 ⭐）
- [Junfei-Z/overleaf-claude-mcp](https://github.com/Junfei-Z/overleaf-claude-mcp) — 编写/推送分叉
