Overleaf MCP Server

Overleaf MCP Server *通过MCP可视化Overleaf和AI之间的桥梁*

*“我试图与Overleaf争论，但它说我的语法无效。”*

背面MCP服务器

MCP（模型上下文协议）服务器，使Claude和其他MCP客户端能够通过Git集成访问Overleaf项目。它可以读取LaTeX文件、解析结构和提取内容，基本上让人工智能窥探你论文的幕后（当然是道德上的）。 🧠

🔗 代表： https://github.com/GhoshSrinjoy/Overleaf-mcp

______________________________________________________________________

执行摘要

该服务器通过MCP连接Overleaf和AI模型。它允许客户端列出、读取和分析LaTeX文件，就像Overleaf是一个本地工作区一样。

一切都是基于Git的，所以你可以进行版本控制，安全访问。Redis队列管理并发性，防止多个项目操作相互踩踏。

简言之： 它位于背侧→ Git → 瑞迪斯→ MCP → 克劳德（或任何客户）。

______________________________________________________________________

商业问题

Overleaf非常适合协作，但很难与Claude或基于LLM的助手等工具集成。你要么：

• 手动复制粘贴LaTeX，或
• 以不可扩展的方式扰乱API端点和令牌。

此MCP服务器使Overleaf“AI可读”。它允许LLM获取内容、检查部分和总结论文，而不会暴露令牌或损坏存储库。非常适合研究小组、人工智能记录员或出版工作流程。

______________________________________________________________________

方法论

运作原理

1. 使用Overleaf的Git集成来克隆和同步项目。
2. 读取文件树并解析 .tex 章节、小节和内容的文档。
3. 通过Redis支持的BullMQ队列分派作业。
4. 每个项目都有自己的Redis锁，以防止竞争条件。
5. 通过MCP协议返回干净的结构化数据。

主要特点

• 📄 文件管理（列出/读取背面文件）
• 📋 文档结构解析（章节和小节）
• 🔍 内容提取（按标题获取特定部分）
• 📊 项目总结（状态、结构概述）
• 🧩 多项目支持
• 🔒 Redis支持的队列用于并发安全
• 🕒 带有截断控件的Git历史记录和差异（引用或工作树）
• ✏️ 安全编辑：使用可选的提交/推送、差异预览和模拟运行检查编写文件

______________________________________________________________________

安装

1. 克隆此存储库

1. 安装依赖项：

   npm install

1. 设置项目配置：

   cp projects.example.json projects.json

1. 编辑 projects.json 使用您的背页凭证：

   {
     "projects": {
       "default": {
         "name": "My Paper",
         "projectId": "YOUR_OVERLEAF_PROJECT_ID",
         "gitToken": "YOUR_OVERLEAF_GIT_TOKEN"
       }
     }
   }

1. 启动Redis实例（本地或远程）。例如：

   docker compose up redis -d

1. 运行MCP服务器：

   npm start

获取背面凭证

1. Git令牌:

- 转到背页帐户设置→ Git集成 - 点击“创建令牌”

1. 项目编号:

- 打开您的背页项目 - 在URL中找到它： https://www.overleaf.com/project/[PROJECT_ID]

配置和环境

服务器通过Redis支持的BullMQ队列协调所有工具调用。使用Redis锁对每个项目的繁重Git操作进行序列化，以避免存储库损坏，同时仍然允许跨不同项目的并发工作。

关键环境变量：

• PROJECTS_FILE：背页项目图的路径（默认值： ./projects.json).
• OVERLEAF_TEMP_DIR：克隆存储库的缓存目录（默认： ./temp).
• REDIS_URL 或 REDIS_HOST/REDIS_PORT/REDIS_PASSWORD/REDIS_DB：Redis连接详细信息。
• REQUEST_QUEUE_NAME：覆盖BullMQ队列名称（默认值： overleaf-mcp-requests).
• REQUEST_CONCURRENCY：排队作业的工作进程并发性（默认值： 4).
• REQUEST_TIMEOUT_MS：服务器等待作业完成的最长时间（默认值： 120000).
• PROJECT_LOCK_TTL_MS, PROJECT_LOCK_RETRY_MS, PROJECT_LOCK_MAX_WAIT_MS：针对每个项目的Redis锁进行高级调优。
• OVERLEAF_GIT_TOKEN, OVERLEAF_PROJECT_ID：可选环境回退（如果未在中定义） projects.json 或工具论点。
• HISTORY_LIMIT_DEFAULT, HISTORY_LIMIT_MAX：默认值 list_history 工具（默认值：20和200）。
• DIFF_CONTEXT_LINES, DIFF_MAX_OUTPUT_CHARS：默认值 get_diff/edit_file 预览（默认值：3和120000）。
• OVERLEAF_GIT_AUTHOR_NAME, OVERLEAF_GIT_AUTHOR_EMAIL：使用时提交需要Git作者/提交者身份 edit_file.

Claude桌面设置

添加到您的Claude Desktop配置文件中：

视窗: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

选项1:Node.js Direct（本地开发）

{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": [
        "/path/to/OverleafMCP/overleaf-mcp-server.js"
      ]
    }
  }
}

需求：本地安装Node.js，本地运行Redis，所有依赖项通过安装 npm install.

选项2:Docker Compose（推荐用于生产环境）

{
  "mcpServers": {
    "overleaf": {
      "command": "docker",
      "args": ["compose", "run", "--rm", "-T", "mcp"],
      "cwd": "/path/to/OverleafMCP"
    }
  }
}

需求：已安装Docker和Docker Compose，项目构建使用 docker compose build. 好处：隔离环境、自动Redis管理、临时容器。

选项3:Docker Exec（持久容器）

{
  "mcpServers": {
    "overleaf": {
      "command": "docker",
      "args": ["exec", "-i", "CONTAINER_NAME", "node", "overleaf-mcp-server.js"]
    }
  }
}

具有特定容器名称的示例:

{
  "mcpServers": {
    "overleaf": {
      "command": "docker",
      "args": ["exec", "-i", "overleaf_mcp-mcp-1", "node", "overleaf-mcp-server.js"]
    }
  }
}

需求:

• 容器已通过运行 docker compose up -d
• 替换 CONTAINER_NAME 使用您的实际容器名称（查找 docker ps)
• 容器必须保持运行，MCP才能工作

何时使用每种方法:

• 选项1：开发和调试
• 选项2：清洁、隔离的生产部署
• 选项3：当您需要持久容器和直接执行控制时

配置后重新启动Claude Desktop。

Docker使用

您可以使用提供的compose文件在容器中完全运行MCP服务器及其Redis依赖项。

基本Docker设置

1. 复制 projects.example.json 到 projects.json 并填写您的凭据。
2. （可选）创建缓存目录，以便克隆在运行过程中持续存在：

   mkdir -p data/cache

1. 构建容器：

   docker compose build

1. 启动Redis和MCP容器：

   docker compose up -d

高级Docker使用

对于临时容器（上述选项2）:

# Start only Redis persistently
docker compose up -d redis

# MCP server will be started on-demand by Claude Desktop

对于持久容器（上述选项3）:

# Start both services and keep them running
docker compose up -d

# Verify containers are running
docker compose ps

# Check container names for your configuration
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

撰写服务地图 projects.json 放入集装箱 /app/projects.json，并将克隆的存储库存储在 ./data/cache 在主机上。

使用 docker compose down 当你想停止所有容器时。

容器管理

查看容器日志:

# MCP server logs
docker compose logs mcp

# Redis logs  
docker compose logs redis

# Follow logs in real-time
docker compose logs -f mcp

容器名称故障排除:

# List all containers with names
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

# If using Option 3, update your Claude config with the correct container name

可用工具

list_projects

列出所有已配置的项目。

list_files

列出项目中的文件（默认值：.tex文件）。

• extension：文件扩展名筛选器（可选）
• projectName：项目标识符（可选，默认为“默认”）

read_file

从项目中读取特定文件。

• filePath：文件路径（必需）
• projectName：项目标识符（可选）

get_sections

从LaTeX文件中获取所有部分。

• filePath：LaTeX文件的路径（必需）
• projectName：项目标识符（可选）

get_section_content

获取特定部分的内容。

• filePath：LaTeX文件的路径（必需）
• sectionTitle：章节标题（必填）
• projectName：项目标识符（可选）

list_history

显示最近的git提交。

• limit：返回的最大提交数（默认20，最大200）
• path：可选路径过滤器
• since / until：git日志时间过滤器（例如。， 2.weeks, 2025-01-01)
• projectName：项目标识符（可选）

get_diff

获取refs或工作树之间的git diff。

• fromRef：Base ref（省略以区分工作树与HEAD）
• toRef：目标引用（省略使用工作树）
• path / paths：可选路径过滤器
• contextLines：统一的差异上下文行（0-10，默认3）
• maxOutputChars：截断此多个字符的差异（默认120000）
• projectName：项目标识符（可选）

edit_file

编写一个文件，并可选择提交/推送更改。

• filePath：目标文件路径（必需）
• content：新文件内容（必填）
• commitMessage：提交消息（默认：“通过背页MCP更新”）
• push：提交后是否推送（默认值：true）
• dryRun：如果为真，则仅报告大小；不要写或承诺
• contextLines / maxPreviewChars：差异预览控件
• projectName：项目标识符（可选）

status_summary

获取全面的项目状态摘要。

• projectName：项目标识符（可选）

使用示例

# List all projects
Use the list_projects tool

# Get project overview
Use status_summary tool

# Read main.tex file
Use read_file with filePath: "main.tex"

# Get Introduction section
Use get_section_content with filePath: "main.tex" and sectionTitle: "Introduction"

# List all sections in a file
Use get_sections with filePath: "main.tex"

# Show last 10 commits
Use list_history with limit: 10

# Show diff between HEAD and previous commit for main.tex
Use get_diff with fromRef: "HEAD~1", toRef: "HEAD", path: "main.tex", contextLines: 5

# Edit and push a file
Use edit_file with filePath: "sections/intro.tex", content: "", commitMessage: "Update intro", push: true

保障措施和限制

• 每个项目的Redis锁可以防止并发的git操作发生冲突。
• 默认情况下，Diff输出被截断(maxOutputChars，默认值为120k）。根据需要调整每次通话。
• 历史查询有上限(limit，默认值20，最大值200）以避免超时。
• edit_file 支持 dryRun 用于大小检查，并返回截断的差异预览；提交可以跳过推送 push: false.
• 所有文件写入都要经过路径验证，以保留在仓库缓存中。

多项目使用

要处理多个项目，请将它们添加到 projects.json:

{
  "projects": {
    "default": {
      "name": "Main Paper",
      "projectId": "project-id-1",
      "gitToken": "token-1"
    },
    "paper2": {
      "name": "Second Paper", 
      "projectId": "project-id-2",
      "gitToken": "token-2"
    }
  }
}

然后在工具调用中指定项目：

Use get_section_content with projectName: "paper2", filePath: "main.tex", sectionTitle: "Methods"

文件结构

OverleafMCP/
├── Dockerfile                 # Container image for the MCP server
├── docker-compose.yml         # Docker Compose stack (server + Redis)
├── overleaf-mcp-server.js     # Main MCP server with Redis-backed queue
├── overleaf-git-client.js     # Git client library
├── package.json               # Dependencies and scripts
├── package-lock.json          # Exact dependency versions
├── projects.example.json      # Configuration template (copy to projects.json)
├── README.md                  # Documentation
└── .dockerignore              # Docker build context exclusions

故障排除

常见问题

1. Claude Desktop中的“服务器已断开连接”:

- 检查容器名称 docker ps - 验证容器是否正在运行 docker compose ps - 检查Redis连接 docker compose logs redis

1. “项目不存在”错误:

- 验证背页URL中的项目ID - 检查Git令牌是否有效且未过期 - 确保在Overleaf项目设置中启用Git集成

1. Redis连接错误:

- 确保Redis容器正在运行： docker compose up -d redis - 检查Redis日志： docker compose logs redis

1. 容器名称不匹配（选项3用户）:

- 查找正确的容器名称： docker ps --format "table {{.Names}}" - 使用精确的容器名称更新Claude Desktop配置 - 容器名称可以包括项目目录前缀（例如。， overleaf_mcp-mcp-1)

为什么Redis很重要

Redis提供了几个关键功能：

• 队列管理：在不阻塞的情况下处理多个并发请求
• 项目锁定：防止多个操作访问同一项目时发生Git冲突
• 工人池管理：在多个工作进程之间分配工作负载
• 生产准备就绪：使服务器具有可扩展性和并发使用的健壮性

如果没有Redis，服务器将适用于单用户场景，但在负载下可能会面临竞争条件和资源耗尽。

安全须知

• projects.json 是否有必要保护您的凭据
• 永远不要提交真实的项目ID或Git令牌
• 使用提供的 projects.example.json 作为模板
• 容器日志可能包含敏感信息-适当安全

引用

如果您在研究中使用此软件，请引用：

@software{overleaf_mcp_2025,
  author = {GhoshSrinjoy},
  title = {Overleaf MCP Server},
  year = {2025},
  url = {https://github.com/GhoshSrinjoy/Overleaf-mcp}
}

技能

该项目涉及：Node.js、Redis（BullMQ）、Docker、Overleaf Git集成、文件解析（LaTeX）、并发作业队列和MCP协议设计。\ 它还展示了AI×研究集成的实际工程——在人类写作工具和模型理解之间架起桥梁。 🧩

______________________________________________________________________

业绩与商业建议

它提供了什么

• 为Claude和其他MCP客户提供无缝的背面访问。
• LaTeX文件和部分的结构化读取。
• 通过Redis队列进行可扩展的多项目处理。
• 无需公开暴露Overleaf API或存储明文令牌。

最适合：

• 研究实验室建立论文助理或总结员。
• 整合学术背景的人工智能工具。
• 开发人员需要安全、并发的背面同步。

建议：\ 使用 Docker编写（选项2） 用于生产：它使Redis和MCP服务器保持隔离和持久。\ 对于本地测试， 节点直接（选项1） 够了。\ 当您需要持久容器和直接控制时，选项3（Docker Exec）非常有用。 🎯

______________________________________________________________________

后续步骤

🧠 使用正则表达式或基于树的解析添加更智能的节提取。\ 🧵 为大型文档集添加工作扩展。\ 🔒 为缓存的存储库添加加密。\ 🧩 扩展对Markdown和BibTeX解析的支持。\ 📦 将预构建的Docker镜像发布到Docker Hub。\ 🧰 添加Redis+锁完整性的CI测试。\ 🤖 为“自动总结LaTeX部分”添加可选的Claude提示

______________________________________________________________________

MIT许可证