OverleafMCP：让 AI 直接「读懂并改写」你的 LaTeX 论文

一位物理学博士的痛苦，与一个 200 星的开源工具

想象这样一个场景：你花了两周写完了一篇 SCI 论文的 Introduction 和 Methodology，第三天打开 Overleaf 发现引用格式混乱、某个章节的逻辑顺序需要调整。此时你面临两个选择——要么手动在 Overleaf 编辑器里一段段复制粘贴让 AI 修改，要么把整个 LaTeX 代码发给聊天窗口，然后面对 AI「无法直接编辑你的文件」的无奈回答。

这就是 OverleafMCP 诞生的背景。项目作者 Minjong Yoo（@mjyoo2）是一名物理学博士，他在撰写论文时深刻体会到了这种割裂感——AI 模型对论文内容「看得见却摸不着」。他决定用 MCP（Model Context Protocol）这座桥，把 AI 和 Overleaf 直接连接起来。

2024 年底发布后，这个仅有 8 个源文件、代码总量不过几百行的小工具迅速获得了学术界和 AI 开发者的关注。截至 2026 年中，GitHub Stars 已突破 200，NPM 包 @mjyoo2/overleaf-mcp 被收录至 MCP 官方生态。

从割裂到融合：MCP 如何打通 AI 与学术写作

MCP 是由 Anthropic 在 2024 年提出的开放协议，核心理念是让 AI 应用与外部工具、数据源之间建立标准化的双向通信通道——类似编程语言领域的 LSP（Language Server Protocol），但面向 AI 时代。传统的 AI 对话模式中，AI 只能「看」到你粘贴进来的文本；而 MCP 允许 AI 直接调用外部工具，感知并操作真实数据。

OverleafMCP 的工作原理清晰而优雅：它将 Overleaf 的 Git 同步功能作为数据通道。Overleaf 本身就内置了 Git 同步功能，用户可以在 Overleaf 设置中开启，获得一个 git.overleaf.com 的远程仓库地址。OverleafMCP 通过这个 Git 端点完成所有文件操作——克隆仓库、读取 LaTeX 文件、解析文档结构、写回修改。整个过程中，Overleaf 服务器仅作为 Git 远程端点使用，不依赖任何 Overleaf 官方 API。

这种设计的优势在于稳定性和可靠性：Overleaf 的 Git 同步功能是官方提供的稳定接口，不存在 API 速率限制或版本变更的风险。AI 对项目所做的任何修改都会经过 Git 提交历史记录，可以随时回滚，这是直接操作 Overleaf API 无法实现的安全保障。

核心能力：从「读」到「写」的全链路支持

OverleafMCP 暴露了六个核心工具，覆盖了学术写作的完整工作流：

文件管理工具：AI 可以列出项目中的所有文件、读取任意 .tex 或 .bib 文件的内容。LaTeX 项目通常包含主文件、多个章节文件、参考文献文件、图片目录等，AI 能够完整感知这个文件系统结构，而不是只能看到用户手动粘贴的一小段文本。

文档结构解析：这是 OverleafMCP 最有技术含量的部分。项目实现了一个纯 JavaScript 的 LaTeX 章节解析器（parseSections 函数），能够处理 \section、\subsection、\subsubsection、\chapter、\part 以及带可选参数 [短标题]{长标题} 的复杂格式。解析器内部实现了大括号平衡算法，即使 LaTeX 命令的标题参数中包含嵌套的格式命令（如 \section{Use of \emph{X}}），也能正确提取完整标题。

章节级编辑：借助 Git 的能力，AI 可以针对特定章节进行精确修改，而不影响其他部分。提交信息中会记录「修改了哪个章节」这一元数据，便于后续追踪。传统方式下让 AI 修改 LaTeX 论文，要么重新生成整段内容（容易引入格式破坏），要么用户手动复制粘贴（完全失去自动化优势），而章节级编辑恰好解决了这个两难问题。

多项目管理：对于同时维护多篇论文的研究者，OverleafMCP 支持通过 projects.json 配置文件管理多个 Overleaf 项目，可以在不同项目之间无缝切换。配置路径遵循各平台规范（macOS/Linux 用 ~/.config/overleaf-mcp/projects.json，Windows 用 %APPDATA%/overleaf-mcp/projects.json）。

极简安装：两分钟接入 Claude Desktop

OverleafMCP 最大的产品设计亮点是零安装成本。用户无需 clone 仓库、无需手动运行 npm install，只需要在 Claude Desktop（或其他 MCP 兼容客户端）的配置文件 claude_desktop_config.json 中添加一段 JSON 配置，重启应用即可：

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "@mjyoo2/overleaf-mcp"],
      "env": {
        "OVERLEAF_PROJECT_ID": "YOUR_PROJECT_ID",
        "OVERLEAF_GIT_TOKEN": "YOUR_OVERLEAF_GIT_TOKEN"
      }
    }
  }
}

所需配置仅有两个：Overleaf 项目的 Git URL 中的 ID，以及 Overleaf 账户设置中生成的 Git 访问令牌。OverleafMCP 会在首次运行时自动将项目克隆到系统的临时目录中，后续操作均在本地缓存的 Git 仓库副本上进行，既保证了速度，也避免了对 Overleaf 服务器的频繁请求。

技术架构：MCP SDK + Git 双引擎

从代码结构看，OverleafMCP 的核心架构非常清晰，仅有两个主要文件：

overleaf-mcp-server.js 是 MCP 服务器的主入口，基于 @modelcontextprotocol/sdk v1.0.0 构建，使用标准 stdio 传输层与 AI 客户端通信。文件内实现了完整的配置加载逻辑（四层优先级：环境变量 → 显式配置文件 → 用户配置目录 → 工作目录）、LaTeX 章节解析器、Git 操作客户端封装，以及六个 MCP 工具的请求处理函数。总代码量约 400 行，职责划分明确。

overleaf-git-client.js 是 Git 操作的封装类，提供了安全的路径解析（防止目录遍历攻击）、仓库克隆/拉取、文件读写、Git 提交等原子操作。值得注意的是，所有 Git 操作中敏感令牌都被脱敏处理——即使在错误日志或标准输出中，令牌也会被替换为 ***。

依赖方面，OverleafMCP 仅依赖 @modelcontextprotocol/sdk，没有引入任何额外的 npm 包，轻量化程度极高。Node.js 版本要求仅为 >=18.0.0，覆盖了当前主流的 Node.js LTS 版本。

局限性与安全考量

尽管设计精巧，OverleafMCP 也存在一些需要注意的局限性。首先，Git Token 的安全存储是用户必须自行解决的问题——当前版本将令牌以明文形式写入环境变量或 projects.json 文件，这意味着任何能访问配置文件的用户都能获取访问权限，生产环境使用建议配合密钥管理工具（如 OVERLEAF_GIT_TOKEN_FILE 指向加密存储的令牌文件）。

其次，OverleafMCP 不提供 Web UI，它是一个纯命令行 MCP 服务器，输出通过 stdio 管道传输。这意味着用户必须使用支持 MCP 协议的 AI 客户端（Claude Desktop、Cursor、Windsurf 等），无法在浏览器中直接操作。

第三，项目代码目前缺乏自动化测试用例，README 中未提及任何测试框架或 CI/CD 配置，代码质量评分的客观性受到一定影响——虽然代码本身风格整洁、结构合理。

学术 AI 工作流的里程碑

OverleafMCP 代表了一个重要趋势：AI 正在从「对话伙伴」进化为「协作工具的操作者」。在 MCP 协议出现之前，AI 只能处理用户主动提供的信息；MCP 让 AI 具备了主动感知和操作外部系统的能力，而 OverleafMCP 则将这种能力带入了学术写作这一具体场景。

从数据看，这个仅 200 星的小项目已经在 MCP 生态中占据了一席之地——被 PulseMCP 收录为官方服务器之一，在 lobehub.com 的 MCP 服务器排行榜上稳定存在。它解决的不是什么宏大的技术难题，而是一个真实、具体、每天都在发生的痛点：AI 和你的论文之间，隔着一道无法逾越的「文件」墙。

对于正在进行学术写作的研究者，OverleafMCP 提供了一条零门槛的 AI 辅助写作路径；对于 AI 开发者，它展示了一个「用 MCP 连接一切」的实际案例，证明了小而美的工具同样可以在开源生态中产生超出其代码规模的影响力。