Overleaf

Overleaf MCP 服务 — 安全编辑 LaTeX 论文

将 Claude Code、Claude Desktop、Codex、ChatGPT、Cursor、VS Code 或任何 MCP 客户端 连接到 Overleaf。读取、搜索、编辑、编译和审阅真实的 LaTeX 项目，无需将论文 复制粘贴到聊天窗口中。

npx --yes [email protected] setup

编辑内容会保留在本地克隆中，直到你明确发布。每次读取和推送之前，此 Overleaf MCP 服务都会检查协作者所做的更改。如果你们修改了相同的行，它会停止推送，并展示两个版本，而不是擅自选定一个。

如果提供可选的 Overleaf 会话 Cookie，编辑内容还可以作为修订建议发送，供合作者接受或拒绝；现有的审阅面板也会变得可读。普通的 Git 推送无法实现这两点。

下载一键安装的 Claude Desktop 安装包 或使用上方的设置命令，将其安装到 Claude Code、Codex、Cursor 和其他本地 AI 客户端。

---

独立社区项目；与 Overleaf 无关联，也未获其认可。

为什么选择这个 Overleaf MCP 服务？

目前有多个 Overleaf MCP 服务。在基于 Overleaf 官方 Git 桥接功能构建的服务中，这是功能最全面的一个，也是唯一一个在合作者已经修改你正在编辑的行时选择停止而非覆盖的服务。

• 冲突会终止推送，而不是覆盖合作者的段落。 每次读取和推送前，都会先检查 Overleaf 上的更改。如果两处编辑修改了相同的行，push_changes 会拒绝操作并展示两个版本。
• 18 个工具，未经你同意，内容不会传到 Overleaf。 按章节或精确文本读取、搜索和编辑，添加、重命名和删除文件，在本地编译，检查差异，然后再决定是否发布。
• 编辑内容可以作为建议发送，而不是直接成为定稿。 3 个可选工具会与 Overleaf 编辑器交互，而非通过 Git 桥接功能操作，因此更改会出现在审阅面板中，供合作者接受或拒绝。Git 推送无法实现这一点。 修订
• 不想用终端也没问题。 Claude Desktop 可通过下载的安装包安装；Claude Code 和 Codex 可作为插件安装。
• 令牌只写入一次，保存在一个权限模式为 600 的文件中。 任何客户端配置都不保存令牌，已发布的插件也完全不声明环境变量。

相关项目逐一比较了其他方案，也同样直言此服务无法实现的功能。

常见工作流包括：按章节修订学术论文、搜索大型 LaTeX 项目、检查参考文献、发布前编译、审阅精确差异，以及将编辑作为修订建议发送到 Overleaf。

安装位置

以下每种方式都会连接到同一个服务和同样的 18 个工具，并且在明确推送之前，所有编辑都会保留在本地。请根据你的客户端选择对应行。只有配置了会话 Cookie 后，才会额外显示这三个跟踪更改工具。

客户端	安装方式
Claude Desktop	下载安装包并双击。一键安装
Claude Code	将此代码库添加为插件市场。两条命令
Codex CLI、桌面应用和 IDE 扩展	同样的方式，使用 Codex 命令。两条命令
Cursor	npx --yes mcp-server-overleaf setup。一条命令
Visual Studio Code	添加一项 .vscode/mcp.json 配置。指南
网页版和桌面版 ChatGPT	使用仅限出站的 Secure MCP Tunnel，无需公开端点，也无需开放端口。指南
可读取 MCP 注册表的目录	已列为 io.github.yangzichao/mcp-server-overleaf。详情
其他任何 MCP 客户端	使用 npx --yes mcp-server-overleaf --stdio，或 Streamable HTTP。手动安装
用于开发的机器	从源代码检出。从源代码安装

Claude Desktop 使用打包安装包；Claude Code 和 Codex 各自使用一个插件。其他客户端都通过 setup 完成同样的操作。四种方式的最终步骤都相同：先向 Overleaf 验证令牌，再将令牌写入权限模式为 600 的单个文件，客户端配置中不会保存密钥。

指南

• 项目配置与高效读取介绍独立凭据、稀疏检出、修订版本读取和受保护的编辑。
• 相关项目介绍现有替代方案，以及本项目对协作者安全和恢复的关注。
• 发布流程与验证介绍经过测试的制品、来源证明、首次发布和后续可信发布。
• 安装 Claude Desktop 安装包介绍一键 .mcpb 扩展：其中包含什么、如何构建以及如何移除。
• 安装 Claude Code 和 Codex 插件介绍两个市场条目：插件包含什么、如何在不保存令牌的情况下获取令牌，以及如何更新、移除或构建插件。
• 将本地 MCP 客户端连接到 Overleaf介绍 Codex 桌面应用和 CLI、Claude Code、Claude Desktop、Cursor、Visual Studio Code、本地 stdio、验证和故障排查。
• 通过 Secure MCP Tunnel 将 ChatGPT 连接到 Overleaf 介绍从本地 stdio 服务连接到 ChatGPT 桌面版和网页版的完整私密连接，包括工作区关联、最小权限凭据、验证和故障排查。

你将安装的内容

一个通过 stdio 或 Streamable HTTP 提供 18 个工具的 MCP 服务；使用会话 cookie 启用跟踪更改后，还会增加 3 个工具。一个核心、两种传输方式；工具实现完全相同，只有消息封装格式不同。setup 会将其连接到这台电脑上的 AI 客户端，是大多数人唯一需要使用的命令。

需要 Node 22.14+ 和可通过 PATH 找到的 git；推荐使用 Node 24 LTS。compile_project 还需要 latexmk 和 TeX 发行版；其他工具均无需这些依赖。

发布测试矩阵涵盖 macOS 和 Linux。Windows 上的 Git 和 TeX 工作流尚未验证。此服务是命令行应用，不是可导入的 JavaScript 库。

项目必须启用 Git 集成。Overleaf 将其说明为一项高级功能，是否可用取决于项目所有者的订阅。因此，即使受邀加入由订阅用户拥有的项目的是免费账户，仍然可以使用该功能；订阅可以是个人、团队或机构订阅。不要告诉用户他们自己的套餐导致无法使用。请改为在步骤 3 中直接验证。

一键安装到 Claude Desktop

下载 mcp-server-overleaf.mcpb 并双击。Claude Desktop 会打开安装面板，提示输入以下两个值，然后自行启动服务。无需终端、无需安装 Node，也无需构建。

• Overleaf 项目地址 — 在 Overleaf 中打开项目，然后从地址栏复制完整 URL。
• Overleaf Git 令牌 — 在 https://www.overleaf.com/user/settings 的 Git 集成部分生成。Claude Desktop 会将其存储在操作系统密钥链中。

该安装包包含与 npm 发布版本相同的服务，以及锁定的运行时依赖，不含其他内容。它仅支持 macOS 和 Windows，因为 Claude Desktop 只能在这两个平台上运行。其他客户端请使用下面的命令。详情请参阅 安装 Claude Desktop 安装包。

安装为 Claude Code 或 Codex 插件

先保存令牌：

npx --yes [email protected] setup --clients none

然后，在 Claude Code 中：

claude plugin marketplace add yangzichao/mcp-server-overleaf
claude plugin install overleaf@mcp-server-overleaf

或者，在 Codex 中：

codex plugin marketplace add yangzichao/mcp-server-overleaf
codex plugin add overleaf@mcp-server-overleaf

重启客户端，然后让它列出项目中的文件。

在这个本地 MCP 服务被公共目录收录之前，两个客户端都从本仓库的市场目录安装它：Claude Code 读取 .claude-plugin/marketplace.json，Codex 读取 .agents/plugins/marketplace.json，两者都指向同一个 plugins/overleaf 目录。该插件不保存令牌，也不设置环境变量，因为第一条命令会将令牌写入 ~/.config/overleaf-mcp/projects.json，服务会从那里查找令牌。公共目录审核与基于本仓库的安装彼此独立。详情请参阅 安装 Claude Code 和 Codex 插件。

使用一条命令安装

npx --yes [email protected] setup

它会检查 Node 和 git，询问项目和令牌，在写入任何内容前验证令牌能否访问 Overleaf，并将服务注册到这台计算机上找到的客户端：Claude Code、Codex、Claude Desktop 和 Cursor。如果运行失败，不会留下半成品配置，因为只有 Overleaf 接受令牌后才会写入内容。

需要准备两样东西，都可以在浏览器中获取：

• 项目地址。 在 Overleaf 中打开项目，复制地址栏中的完整 URL。只读共享链接不是项目地址；安装程序会明确提示这一点，而不是等到之后才失败。
• git 身份验证令牌，可在 https://www.overleaf.com/user/settings 的 Git 集成设置中生成。输入时不会回显令牌。

令牌只会以 600 权限写入 ~/.config/overleaf-mcp/projects.json，不会写入其他位置。服务会自行找到该文件，因此客户端配置中不会保存机密、文件路径或任何环境变量。客户端使用绝对 Node 路径和绝对入口点注册，而不是使用 npx，因为桌面应用的 PATH 远比终端中的 PATH 短。

之后重启 Claude Desktop、Cursor 或 Codex；Claude Code 会在下次运行时加载它。然后让助手列出项目中的文件。

也可以在无人值守的情况下运行安装程序：

printf '%s' "$OVERLEAF_TOKEN" | npx --yes [email protected] setup \
  --project paper=https://www.overleaf.com/project/64a1b2c3d4e5f6a7b8c9d0e1 \
  --token-stdin --yes

--clients claude-code,codex 用于指定只修改哪些客户端，--clients none 则会写入配置，但不注册任何客户端。再次运行即可添加另一个项目或替换已过期的令牌；旧文件会保留在旁边。

在 MCP 注册表中查找

该服务已列入官方 Model Context Protocol 注册表，名称为 io.github.yangzichao/mcp-server-overleaf。条目列出了 npm 软件包和 Claude Desktop 捆绑包；读取该注册表的客户端和目录会从中获取此服务。发布工作流会发布条目本身，因此它绝不会指向 npm 上不存在的版本。

Claude Code 和 Codex 不会读取该注册表。它们有自己的插件市场，见上文；也可以手动添加该服务：

claude mcp add --transport stdio --scope user overleaf -- npx --yes [email protected] --stdio
codex mcp add overleaf -- npx --yes [email protected] --stdio

这两种配置形式都需要在环境中设置 OVERLEAF_GIT_TOKEN 和 OVERLEAF_PROJECT_ID，因此 setup 会改为写入 projects.json 并注册绝对路径。

手动从 npm 安装

如果你想查看每个步骤，或配置客户端设置指南未涵盖的内容，请使用此方式。 以下命令明确指定了版本 0.3.9，以免客户端重启时悄悄升级服务。 如果该版本尚未发布，请使用下方的源代码安装方式。npm 会安装编译后的 JavaScript 和锁定的运行时依赖；无需本地构建。

npx --yes [email protected] --version

请将配置保存在 npm 安装目录和 npx 缓存之外。创建一个私有文件：

mkdir -p "$HOME/.config/overleaf-mcp"
touch "$HOME/.config/overleaf-mcp/env"
chmod 600 "$HOME/.config/overleaf-mcp/env"

在本地编辑该文件，填入你的令牌和项目 ID：

OVERLEAF_GIT_TOKEN=olp_your_token_here
OVERLEAF_PROJECTS=paper=64a1b2c3d4e5f6a7b8c9d0e1

对于使用 mcpServers JSON 格式的客户端：

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["--yes", "[email protected]", "--stdio"],
      "env": {
        "OVERLEAF_MCP_ENV_FILE": "/absolute/path/to/.config/overleaf-mcp/env"
      }
    }
  }
}

将文件路径替换为实际的绝对路径；JSON 不会展开 ~ 或 $HOME。 使用其他配置格式的客户端，应使用相同的环境变量启动相同的命令和参数。如果桌面应用找不到 npx，请使用 command -v npx 查到的绝对路径。有关源代码安装示例和特定客户端的配置位置，请参阅客户端指南。

或者，在客户端的 env 中设置 OVERLEAF_GIT_TOKEN 和 OVERLEAF_PROJECTS。通过 OVERLEAF_MCP_ENV_FILE 指定的文件中，环境变量会覆盖各个文件值；如果明确指定的文件路径无法读取或是相对路径，则会报错。未设置该变量时，仅当客户端未提供项目或凭据设置（包括文件路径）时，才会使用安装目录中的 .env。JSON 项目文件可以提供独立的凭据；请参阅配置指南。 配置搜索绝不会检查当前工作目录。

重启客户端后，调用 list_projects 检查配置，再调用 list_files 验证是否能访问实际项目。仅发现工具并不能证明 Overleaf 访问正常。

从源代码检出版本安装

第 1 步：构建

npm ci && npm run build

继续之前，请确认 dist/index.js 存在。记下仓库根目录的绝对路径；以下每项客户端配置都需要该路径，而且相对路径无法使用，因为客户端会从任意工作目录启动服务。

第 2 步：向用户收集两个值

Git 身份验证令牌。 在 https://www.overleaf.com/user/settings 的 Git 集成部分生成。一个令牌可用于用户的所有项目，有效期为一年。令牌以 olp_ 开头。

让用户使用第 3 步中的命令自行将令牌粘贴到 .env 中，而不要粘贴到聊天中。粘贴到对话中的令牌会永久保留在记录里，必须轮换。如果用户还是粘贴了，请明确告知他们应轮换令牌，然后继续。

一个或多个项目 ID。 项目 URL 中最后一段路径： https://www.overleaf.com/project/<projectId>。项目 ID 恰好由 24 个十六进制字符组成。其他任何内容都不是项目 ID；请让用户重新提供，不要猜测。

第 3 步：写入 .env 并验证令牌是否有效

cp .env.example .env && chmod 600 .env

然后让用户填写：

OVERLEAF_GIT_TOKEN=olp_...
OVERLEAF_PROJECTS=paper=64a1b2c3d4e5f6a7b8c9d0e1

OVERLEAF_PROJECTS 是以逗号分隔的 name=projectId 键值对列表。名称是用户自行选择的任意标签。也接受不带名称的项目 ID，此时会以该 ID 本身作为名称注册。只注册了一个项目时，它会成为默认项目；注册了多个项目时，请设置 OVERLEAF_DEFAULT_PROJECT、使用名为 default 的别名，或在每次调用时指定项目名称。

配置任何客户端之前，请先验证凭据能否连接 Overleaf：

git ls-remote https://[email protected]/<projectId>

Git 会提示输入密码。这里应输入令牌。输出引用信息表示令牌有效。403 或 Repository not found 表示令牌错误，或者该账户的套餐不包含 Git 集成功能；请在继续之前解决此问题，因为所有工具都依赖它。

服务会自行读取 .env，因为 MCP 客户端会在没有 shell 的情况下启动服务。这样令牌只需保存在一个文件中，其权限由用户控制，而不必复制到每个客户端的配置中。客户端在环境中显式设置的任何值仍具有优先权。

步骤 4：向客户端注册

使用步骤 1 中的绝对路径。只配置用户实际指定的客户端。 有关客户端特定的配置位置、验证和故障排除，请参阅 本地 MCP 客户端指南。

Claude Code

claude mcp add overleaf -s user -- node /absolute/path/to/mcp-server-overleaf/dist/index.js --stdio

然后运行 claude mcp list，确认它显示 ✔ Connected。在确认看到该结果之前，不要报告成功。

Claude Desktop 或 Cursor — 将配置添加到客户端的 MCP 配置文件中。文件位置和重启步骤因客户端而异；本地 MCP 客户端指南列出了两者。

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

Codex 桌面端、CLI 或 IDE 扩展 — 同一台 Codex 主机上的客户端共用 ~/.codex/config.toml：

[mcp_servers.mcp-server-overleaf]
command = "node"
args = ["/absolute/path/to/mcp-server-overleaf/dist/index.js", "--stdio"]

如果用户希望读取操作自由执行，同时每次写入都需先确认，请在服务表中添加 default_tools_approval_mode = "writes"。

ChatGPT 桌面端本地 MCP 设置可以直接在存放此仓库的计算机上启动相同的 stdio 命令。此本地配置与同一主机上的 Codex 客户端共用；本地 MCP 客户端指南包含 UI 和 CLI 的操作路径。

ChatGPT 网页版或工作区共享的 ChatGPT 应用 — 使用 OpenAI Secure MCP Tunnel，无需将服务暴露到公共互联网。ChatGPT 连接到由 OpenAI 托管的隧道端点，而 tunnel-client 会将请求转发到 dist/index.js --stdio。请按照Secure MCP Tunnel 分步指南操作；其中包含所需的 Platform 组织和 ChatGPT 工作区关联、运行时密钥、开发者模式应用设置，以及端到端验证。

通过 HTTP 连接的远程客户端

node dist/index.js --http --port 3017

由于任何能够访问该端口的人都可能读取和改写用户的论文，因此如果没有 OVERLEAF_MCP_HTTP_AUTH_TOKEN，--http 将拒绝启动。--allow-anonymous 会覆盖此限制，仅应在该端口确实无法从计算机外部访问时使用。不要用它来绕过缺少令牌的问题。

步骤 5：端到端验证

调用 list_files。如果返回文件列表，就说明整条链路均可正常工作：配置、令牌、克隆和客户端连接。如果失败，错误文本会说明原因。

工具

每个工具都接受一个可选的 project：项目的 Overleaf 地址、原始 24 字符 ID，或 OVERLEAF_PROJECTS 中的名称。省略该参数时使用默认项目。接受地址是因为它是你已有的形式，因此只需粘贴地址即可访问从未配置过的论文。未注册的项目需要默认 Git 令牌；已注册的项目则使用各自配置的项目凭据。

工具	功能
list_projects	此服务可访问的项目
list_files	按类型分组的文件；支持扩展名筛选和可选的本地新文件
read_file	文本或行范围；可选支持识别修订版本的完整、未更改或增量读取
list_sections	.tex 文件中的分节命令及其行范围
read_section	按标题查找的某个分节正文
search_project	搜索受跟踪的文本文件
replace_text	替换精确片段；遇到匹配不唯一时拒绝操作
edit_section	整体替换某个分节
write_file	覆盖或创建文件
delete_file	删除文件；推送前仅在本地生效
move_file	移动或重命名文件；如果目标已存在则拒绝操作
show_diff	所有尚未推送内容的差异
discard_local_changes	丢弃未推送的编辑和提交，恢复到 Overleaf 上的版本
project_status	同步状态、待处理的编辑、近期历史记录
project_summary	JSON 文件数量、主文档、分节和待处理的更改
sync_project	从 Overleaf 拉取
compile_project	使用 latexmk 编译并报告错误
push_changes	提交并发布，同时检查协作者

如何安全地使用工具

在调用 push_changes 前，编辑只保存在本地。这是整个设计的核心，并非实现细节；正因如此，糟糕的编辑可以被丢弃，而不会发布出去。

调用 push_changes 前，请先阅读 show_diff。只推送一次，并使用真实的提交说明；用户会在 Overleaf 的历史记录中看到这条记录，与合作者的记录并列。

push_changes 可能返回 conflict-with-collaborator。这表示你工作期间有人编辑了相同的行。没有任何内容被发布，两个版本都完好无损。不要重试，不要强制推送，也不要尝试自行合并这两个版本。报告冲突并让用户决定。

推送被拒绝后，提交仍会留在克隆中，因此克隆会同时领先和落后于 Overleaf，此后每次同步都会在相同行上发生冲突。解决方法是调用 discard_local_changes：它会丢弃未推送的提交以及未提交的编辑，并使克隆恢复为 Overleaf 当前的内容。调用前请告诉用户将丢弃哪些内容，因为他们的编辑也会被丢弃。

如果某段文本出现多次，replace_text 会拒绝替换，而不会悄悄只修改第一个匹配项。请添加上下文，使其具有唯一性；或者有意传入 replaceAll。

优先使用 replace_text 和 edit_section，而不是 write_file。write_file 会替换整个文件，因此如果只重建文档的一部分，其余内容会在不提示的情况下被删除。

与其他编辑一样，delete_file 和 move_file 在调用 push_changes 前只影响本地，因此在推送前随时可以通过 discard_local_changes 撤销删除。它们都不会改写 LaTeX 引用：移动文件后，请对旧路径调用 search_project，并修复仍引用该路径的任何 \input、\include 或 \includegraphics，否则论文将无法编译。删除前，请确认该文件确实未被使用——合作者的 \input 就足以导致其构建失败。

对于读取–编辑流程，请使用 mode: "full" 或 "smart" 调用 read_file，并将返回的 revision 作为 expectedRevision 传给任何编辑工具。如果自读取后有合作者或其他客户端更改了文件，编辑操作就会拒绝覆盖。请参阅修订版本协议。

编译不是必需步骤，也不是发布门槛。push_changes 不会检查文档是否能成功构建，因此如果不先检查，损坏的文档也可能被发布。

配置参考

变量	含义
OVERLEAF_GIT_TOKEN	默认凭据；除非通过令牌文件或按项目提供凭据，否则为必需项。
OVERLEAF_GIT_TOKEN_FILE	默认令牌文件的绝对路径。
OVERLEAF_PROJECTS_CONFIG	包含独立凭据的 JSON 项目文件的绝对路径。
OVERLEAF_PROJECT_ID / OVERLEAF_PROJECT_NAME	OVERLEAF_PROJECTS 的单项目替代方案。
OVERLEAF_MCP_ENV_FILE	外部配置文件的绝对路径；使用 npm/npx 时建议配置。
OVERLEAF_PROJECTS	name=projectId 对；使用 JSON 或原始 ID 访问时可选。
OVERLEAF_DEFAULT_PROJECT	调用中省略 project 时使用的已注册名称。
OVERLEAF_MCP_CHECKOUT_MODE	full（默认）或 text-only；请参阅配置指南中的展开行为。
OVERLEAF_MCP_WORKSPACE_DIR	克隆的存放位置。默认值为 ~/.overleaf-mcp/projects。
OVERLEAF_GIT_BASE_URL	默认值为 https://git.overleaf.com。
OVERLEAF_MCP_COMPILE_TIMEOUT_MS	编译超时时间。必须为正整数。
OVERLEAF_MCP_HTTP_AUTH_TOKEN	--http 所需的 Bearer 令牌。
OVERLEAF_MCP_HTTP_PORT	--http 使用的端口。--port 可覆盖此值。
OVERLEAF_SESSION_COOKIE	Overleaf 会话 Cookie。启用三个修订跟踪工具。
OVERLEAF_SESSION_COOKIE_FILE	保存相同值的文件的绝对路径。优先于环境变量。
OVERLEAF_WEB_BASE_URL	这些工具使用的 Overleaf 网页地址。默认值为 https://www.overleaf.com。

它为何如此运行

Overleaf 的 git 桥接并不是通用的 git 远程仓库。每个项目都只有一个分支，且只有一条线性历史；强制推送会被拒绝，也不支持标签、子模块或 LFS。 此处的所有操作都遵循这些限制。

真正的风险不是推送失败，而是悄无声息地覆盖合作者的内容，因此写入和发布是分开的：

1. 每次读取和编辑都会先与 Overleaf 同步。如果本地工作导致无法同步，调用就会失败并保留这些工作。先用 show_diff 检查，然后发布，或明确丢弃，再继续；过时的读取和编辑都会被拒绝。
2. 编辑只会写入本地克隆。只有调用 push_changes 后，内容才会同步到 Overleaf。
3. push_changes 会在推送前立即重新检查 Overleaf，并将此期间新增的内容变基到当前分支上。如果无法干净地应用，推送就会被拒绝并报告冲突，而不会擅自猜测如何解决。

Git 凭据通过凭据助手交给 git，因此身份验证令牌不会出现在 argv 和 .git/config 中。Git 诊断信息会对选定的凭据进行脱敏；工具错误会对所有已配置的项目凭据进行脱敏。请勿将机密放入项目文件中，因为连接的客户端可以读取这些文件。

编译会在克隆目录之外写入文件，因此 .aux、.log 和 .pdf 文件永远不会被暂存并推送回去。克隆还带有本地排除列表，因此 .DS_Store 不会进入合作者的项目。

每个项目的工具调用都会串行执行：先经过进程内队列，再经过工作区下的锁目录。因此，第二个服务进程（例如在两个客户端中注册了同一个服务）会等待，而不是与其争用。

客户端提供的路径会经过两次检查：先作为路径检查一次，再在解析符号链接后根据文件系统检查一次。因此，克隆目录中的链接无法指向目录外部或 .git 内部。

目录结构

src/
  config/      environment parsing, secret redaction
  overleaf/    git command runner, repository operations, project registry, path safety
  latex/       section parsing, file categorization
  workflow/    sync-before-edit, publish-with-conflict-check, compile
  tools/       MCP tool definitions
  transport/   stdio and Streamable HTTP
  server/      server factory shared by both transports
tests/
  config/ latex/ overleaf/  unit tests, run in-process
  features/                 Gherkin specifications, bound to the server over stdio
  integration/              spawn the built server and speak MCP to it over stdio or HTTP

开发

npm run check

一次运行即可执行类型检查、Biome、构建和测试。 类型检查也会覆盖测试代码。每次运行 Vitest 前都会先构建服务，包括聚焦运行和覆盖率测试，因此子进程测试不会使用旧的 dist。

命令	功能
npm run typecheck	对源代码、测试和 Vitest 配置进行类型检查
npm run lint	使用 Biome 检查代码规范和格式
npm run format	使用 Biome 应用修复
npm test	构建，然后运行 Vitest 全套测试
npm run package:check	构建两次、比较压缩包、按用户实际使用方式安装，并测试安装后的服务
npm run check:release	源代码检查、软件包检查和依赖审计
npm run test:coverage	构建，然后运行带 v8 覆盖率的 Vitest

测试套件会通过 stdio 和 HTTP 覆盖相同的工具契约，包括架构、错误标记、读取、编辑、审查和发布。恢复测试会检验脏工作区同步、冲突恢复、远程拒绝和重新连接、进程重启、锁持有进程被终止以及客户端并发操作。新增文件和未推送的提交必须在 show_diff 中可见。确定性的子进程夹具会测试 Git 和编译器超时，无需网络连接或安装 TeX。

tests/features/ 通过 Gherkin 功能文件描述发布契约：用简单的句子说明合作者能看到什么，并将每句话绑定到通过 stdio 对服务发起的真实调用。没有绑定的句子会导致运行失败，因此文档不会偏离其描述的行为。添加场景时，请在 .feature 文件中编写场景，并在其旁边的 .test.ts 文件中绑定新步骤；同一功能的各个场景会共享步骤，因此大多数新场景都无需添加绑定。 依赖 TeX 的测试共用一项可用性检查。设置 OVERLEAF_TEST_TEX=skip 可在没有 TeX 的情况下运行，设置 OVERLEAF_TEST_TEX=required 则会在缺少 latexmk 或 pdflatex 时失败。默认值 auto 会在这两个可执行文件都可用时运行这些测试。GitHub Actions 会在 Linux 和 macOS 上使用 Node 22.14、24 和 26 运行核心检查，此外还有一个会安装 TeX 并要求运行编译测试的 Linux 任务。

npm-shrinkwrap.json 是权威的依赖锁定文件。使用 npm 更新它，并与 package.json 一同提交。发布包中的副本是该文件的运行时部分：prepack 会移除开发依赖项，postpack 会恢复完整锁定文件，因为 npm 会根据随包发布的锁定文件构建依赖树；否则每位用户的机器上都会安装编译器、代码检查工具和测试运行器。如果 tarball 中的 shrinkwrap 仍描述开发依赖项，软件包检查就会失败。 发布软件包测试会在无关的工作目录中，针对已安装的 tarball 重用集成测试套件，覆盖 stdio、HTTP、编辑、冲突和恢复。

该安装会从注册表重新解析声明的范围，而不是读取归档包自身的 shrinkwrap，因此它测试的是这些范围允许的最新依赖树，并按结构而非版本与锁定文件进行比较。一个依赖项只出现在其中一棵依赖树中，或版本相差一个主版本（对于 0.x 软件包则是一个次版本），都会导致检查失败——未固定版本的对等依赖项可能造成这种情况，即使没有任何直接依赖项发生变化。较新的补丁版本或次版本只会被打印出来，运行 npm update 即可更新锁定文件的版本：两棵依赖树都会接受测试；如果要求版本必须一致，那么在没有改动依赖项的分支上，每次上游发布补丁版本都会导致检查失败。

测试绝不会接触真实的 Overleaf。tests/integration/fakeOverleafRemote.ts 会搭建一个裸 Git 仓库，并克隆出第二份仓库来模拟共同作者，从而重现安全约定所依赖的所有操作：fetch、rebase 和被拒绝的推送。

覆盖率报告偏低。集成测试会将 node dist/index.js 作为独立进程启动，而 v8 无法对其子进程进行插桩，因此 src/tools/ 和 src/server/ 的覆盖率显示为 0%，尽管它们已经通过真实的 MCP 线路协议完成端到端测试。

常见问题

Claude Code 或 Claude Desktop 能否编辑 Overleaf 项目？

可以。Claude Desktop 可以安装一键式 .mcpb 软件包，而 Claude Code 可以将该仓库作为插件安装，或通过 stdio 运行 npm 软件包。两者都提供相同的安全工作流，支持读取、编辑、编译、查看差异和推送。

Codex、ChatGPT、Cursor 或 VS Code 能否连接到 Overleaf？

可以。Codex 可以安装随附的插件，Cursor 和其他本地客户端可以运行 npm 软件包，VS Code 可以使用 .vscode/mcp.json，ChatGPT 则可以通过仅出站的 Secure MCP Tunnel 连接。要寻找最直接的方式，请从客户端表格开始。

AI 编辑会覆盖共同作者的工作吗？

不会悄悄覆盖。服务会在读取和写入前进行同步，在明确调用 push_changes 前保留本地编辑，并在发布前立即再次检查 Overleaf。如果共同作者修改了相同的行，推送就会被拒绝，两个版本都会保留。

免费的 Overleaf 账户可以使用吗？

16 个基于 Git 的工具要求项目启用 Git 集成功能。Overleaf 会根据项目所有者符合条件的订阅开放此功能，因此，当项目所有者通过个人、团队或机构套餐获得访问权限时，受邀的免费账户也可以使用。

它能编译 LaTeX 并显示修订记录吗？

可以。安装 latexmk 和 TeX 发行版后，compile_project 会在本地运行。使用可选的 Overleaf 会话 Cookie 后，还可以使用另外三个审阅工具来创建修订建议、列出修订记录和评论，以及对选定文本发表评论。

隐私政策

该服务完全运行在你的计算机上。它不包含分析或遥测功能，也没有任何后台服务。它唯一的出站流量是通过 HTTPS 使用 Git 连接到 Overleaf。Claude Desktop 安装此软件包时，你的令牌会存储在操作系统密钥链中；否则，令牌会存储在由 setup 写入的权限模式为 600 的文件中，并且会从错误输出中脱敏。

工具返回的任何内容都会成为你所连接的 MCP 客户端会话的一部分，并按照该客户端自身的政策处理。

全文：docs/privacy-policy.md。

许可证

MIT