overleaf-mcp-server

Overleaf MCP 服务

通过 Git 同步管理 Overleaf 项目的 MCP 服务。

PyPI 软件包 · MCP Registry

此服务的功能

• 通过 Git 同步，将兼容 MCP 的客户端连接到你的 Overleaf 项目。
• 提供文件级工具，用于列出、读取、写入和同步项目内容。
• 简化工作流：拉取最新文件、编辑，然后推送回 Overleaf。

架构

flowchart LR
  C[MCP Client\nClaude Desktop / other MCP host] -->|Tool Call| S[Overleaf MCP Server]
  S -->|Git Sync| O[Overleaf Git Remote]
  S -->|Read / Write| L[Local Repo Mirror]
  L -->|Commit + Push| O
  O -->|Pull / Fetch| L
  S -->|Tool Result| C

工具工作流

sequenceDiagram
  participant Client as MCP Client
  participant Server as Overleaf MCP Server
  participant Local as Local Mirror
  participant Overleaf as Overleaf Git

  Client->>Server: list_files / read_file
  Server->>Local: Ensure local clone
  Server->>Overleaf: git pull
  Overleaf-->>Server: latest content
  Server-->>Client: file list / file content

  Client->>Server: write_file(path, content)
  Server->>Local: update file
  Server->>Local: git commit
  Server->>Overleaf: git push
  Server-->>Client: success + metadata

要求

• Python 3.13+
• uv 包管理器
• 支持 Git 集成 的 Overleaf 套餐（个人、团队或机构许可）。请通过 Overleaf for Institutions 查看你的机构是否提供免费访问权限——请使用机构邮箱。如果你的机构未列出，请升级套餐。

Git 设置

1. 启用 Git - 在 Overleaf 中打开项目 → Menu → 在 Integrations 下启用 Git。
2. 复制项目 ID - 从浏览器 URL 中获取（例如，https://www.overleaf.com/project/69a4f7cc4eaf13bd56de5b04 → 69a4f7cc4eaf13bd56de5b04）。
3. 生成 Git 令牌 - Account Settings → Git integration authentication tokens → Generate new token。
4. 配置 .env - 将 .env.example 复制为 .env，并填写：

OVERLEAF_TOKEN=your_git_token
PROJECT_ID=your_project_id

project_id 也可以在每次工具调用时传入，但服务配置仍要求设置 PROJECT_ID。

Overleaf Git 令牌是适用于整个账户的凭证。请仅将其存储在 MCP 客户端的环境变量中或受保护的 .env 文件中；如果令牌泄露，请及时轮换。

安全须知

Overleaf 项目中的文件是不可信输入。.tex 文件或项目配置可能包含针对模型的指令；请将文件内容视为数据，而非命令。请将 OVERLEAF_ALLOWED_PROJECTS 限定为服务应能访问的项目：

OVERLEAF_ALLOWED_PROJECTS=project_id_a,project_id_b

默认允许列表仅包含 PROJECT_ID。

快速开始

git clone https://github.com/younesbensafia/overleaf-mcp-server.git
cd overleaf-mcp-server
uv sync
cp .env.example .env   # then edit with your token/project id
uv run overleaf-mcp

如果不使用检出，可直接运行 Git 版本：

uvx --from git+https://github.com/younesbensafia/overleaf-mcp-server overleaf-mcp

只有在项目发布到 PyPI 后，才适合使用普通的 uvx overleaf-mcp。

服务通过 stdio 监听——将 MCP 客户端（如 Claude Desktop）连接到该服务。

对于大型项目，请先调用 sync_project。首次 Git 克隆可能需要较长时间，超过 MCP 客户端单次工具请求的超时时限。

可用工具

工具	描述
list_files	从 Overleaf 项目拉取并列出文件
read_file	读取文件内容
write_file	覆盖整个文本文件，提交并推送到 Overleaf
edit_file	替换一个精确匹配的文本，提交并推送到 Overleaf
sync_project	强制从 Overleaf 拉取并同步

read_file 支持可选的从零开始的 offset 和有界的 limit 行参数，便于分块读取大型文档。

Claude Desktop 设置

添加到 ~/.config/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "overleaf": {
      "command": "uv",
      "args": ["--directory", "/path/to/overleaf-mcp-server", "run", "overleaf-mcp"],
      "env": {
        "OVERLEAF_TOKEN": "your_git_token",
        "PROJECT_ID": "your_project_id"
      }
    }
  }
}

故障排除

• Git 操作出现 403 Forbidden：
  • 你的套餐不包含 Git 集成——请按照 Git 设置 部分进行操作。
  • 或者 Git 令牌不正确——请前往 Account Settings → Git integration authentication tokens 重新生成。
• 项目内容错误：
  • 在 .env 中设置正确的 PROJECT_ID。
  • 或在工具调用中显式传入 project_id。
• 同步冲突：
  • 如果远程内容有更改，请在调用 write_file 前运行 sync_project。
• 服务无法启动：
  • 确保已使用 uv sync 安装依赖项。
  • 确认 Python 3.13+ 可用。

License

MIT - See LICENSE