内容
# Overleaf MCP 服务器
一个 [模型上下文协议](https://modelcontextprotocol.io/)（MCP）服务器，通过 Git 将您的 Overleaf LaTeX 项目连接到 AI 代理。直接从 Claude、Cursor、QoderWork 或任何兼容 MCP 的客户端读取、写入、同步和编译 Overleaf 项目。
## 功能
- **项目管理** — 注册、列出和删除 Overleaf 项目
- **文件操作** — 读取、写入和列出项目中的文件
- **Git 同步** — 拉取最新更改并将编辑推送回 Overleaf
- **LaTeX 编译** — 在本地编译并解析错误/警告日志（需要本地 LaTeX 引擎）
所有文件修改都会在本地自动提交。您可以控制何时将更改推送到 Overleaf，从而实现安全的审核后推送工作流程。
## 工具
| 工具 | 描述 |
|------|-------------|
| `list_projects` | 列出所有已注册的 Overleaf 项目 |
| `add_project` | 通过 Git 从 Overleaf 注册和克隆项目 |
| `remove_project` | 从注册表中删除项目（保留本地文件） |
| `pull_project` | 从 Overleaf 拉取最新更改（`git pull --rebase`） |
| `list_files` | 列出项目目录中的文件 |
| `read_file` | 读取项目中的文件 |
| `write_file` | 写入文件内容（在本地自动提交，不推送） |
| `push_changes` | 将本地提交推送到 Overleaf |
| `compile_project` | 在本地编译 LaTeX 并返回错误/警告 |
## 先决条件
- **Node.js** >= 18
- **Git** 已安装并可在 PATH 中使用
- **Overleaf Git 访问** 已为您的项目启用：
1. 在 Overleaf 上打开您的项目
2. 点击 **菜单** （左上角）
3. 将 **Git** 切换为 **开启**
- **LaTeX 引擎** （可选，用于 `compile_project`）：`latexmk`、`pdflatex`、`tectonic` 或 `xelatex` 之一
### 首次 Git 认证
Overleaf 需要 Git 操作的身份验证。在使用 `add_project` 之前，在终端中运行一次克隆命令以存储凭证：
```bash
git clone https://git.overleaf.com/<您的项目 ID>
```
在提示时输入您的 Overleaf 电子邮件和密码（或 [访问令牌](https://www.overleaf.com/user/settings#git-integration)）。之后，MCP 服务器可以克隆和同步而无需重新输入凭证。
> **注意：** 如果您通过 Google 或其他第三方提供商登录 Overleaf，您需要先在 [Overleaf 账户设置](https://www.overleaf.com/user/settings) 中设置密码。
## 安装
### 1. 克隆和安装
```bash
git clone https://github.com/fh120/overleaf-mcp.git
cd overleaf-mcp
npm install
```
### 2. 配置您的 MCP 客户端
将服务器添加到您的 MCP 客户端配置中。将路径替换为您的实际安装路径。
#### Claude Desktop
编辑 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"overleaf": {
"command": "node",
"args": ["/路径/到/overleaf-mcp/index.mjs"]
}
}
}
```
#### Cursor
前往 **设置 → MCP → 添加 MCP 服务器**，选择类型 `command`，并输入：
- **命令：** `node`
- **参数：** `/路径/到/overleaf-mcp/index.mjs`
#### QoderWork
前往 **设置 → 连接器 → 自定义 MCP → 添加**，粘贴：
```json
{
"mcpServers": {
"overleaf": {
"command": "node",
"args": ["/路径/到/overleaf-mcp/index.mjs"]
}
}
}
```
#### Windsurf / Cline / Continue
遵循各自的 MCP 服务器配置文档。格式相同：
```json
{
"command": "node",
"args": ["/路径/到/overleaf-mcp/index.mjs"]
}
```
## 使用示例
### 注册项目
询问您的 AI 代理：
> “添加我的 Overleaf 项目，ID 为 `6a1cf19e521e2b6b65506658`，并将其命名为 `my-paper`”
这会将项目克隆到服务器目录中的 `workspace/my-paper/`。
### 读取和编辑文件
> “从 `my-paper` 读取 `main.tex`”
> “在 `my-paper` 中，将 `main.tex` 中的摘要更新为：...”
更改会在本地自动提交。要同步到 Overleaf：
> “将更改推送到 my-paper”
### 从 Overleaf 同步
> “从 Overleaf 拉取 `my-paper` 的最新版本”
### 在本地编译
> “编译 `my-paper` 并显示任何错误”
需要本地 LaTeX 引擎。如果未找到，则工具会返回安装说明。
## 项目结构
```
overleaf-mcp/
├── index.mjs # MCP 服务器（所有工具在一个文件中）
├── package.json
├── config.json # 自动生成的项目注册表（gitignored）
├── workspace/ # 克隆的项目存放在这里（gitignored）
└── .gitignore
```
## 工作原理
```
┌─────────────┐ MCP（stdio） ┌──────────────────┐ git clone/push/pull ┌──────────┐
│ AI 代理 │◄───────────────────►│ Overleaf MCP │◄──────────────────────────►│ Overleaf │
│ （Claude， │ │ 服务器 │ │ Git │
│ Cursor..） │ │ （Node.js） │ │ 服务器 │
└─────────────┘ └──────────────────┘ └──────────┘
```
1. AI 代理通过 MCP stdio 传输发送工具调用
2. 服务器将调用转换为本地项目克隆上的 Git 操作
3. 通过 `git push` 和 `git pull` 将更改同步到/从 Overleaf
## 故障排除
### Git 克隆失败，出现身份验证错误
在终端中运行 `git clone https://git.overleaf.com/<项目 ID>` 以存储凭证。如果您使用 Google/第三方登录，请在 [Overleaf 设置](https://www.overleaf.com/user/settings) 中设置密码。
### Git Credential Manager（GCM）挂起
在 Windows 上，GCM 可能导致非交互式终端超时。在启动服务器前设置以下环境变量：
```bash
export GCM_INTERACTIVE=never
export GCM_AUTODETECT_TIMEOUT=1
export GIT_TERMINAL_PROMPT=0
```
### `compile_project` 表示未找到 LaTeX 引擎
安装以下之一：
- [MiKTeX](https://miktex.org/download)（Windows，推荐）
- [TeX Live](https://tug.org/texlive/)（跨平台）
- [Tectonic](https://tectonic-typesetting.github.io/)（轻量级）
或将更改推送到 Overleaf 并通过 Web 界面编译。
## 许可证
MIT
