overleaf-claude-mcp

将 Claude 连接到你的 Overleaf 账户。Claude 可以列出你的项目、选择一个项目、读取 LaTeX 和图片、编辑文件、编译，并把 PDF 取回来。

Overleaf 的免费版没有公开 API：Git 桥接和 Dropbox 同步都是 Premium 功能。因此，这个服务器使用与 Overleaf Web 应用相同的内部 HTTP 和 socket 端点，并通过你一次性创建的浏览器会话进行认证。每个端点都是从 Overleaf 自己的 JavaScript 包中解析出来，然后在真实账户上实际验证过的。参见已验证的端点。

教程

你需要什么

• Node 20 或更新版本（node -v）

• 已安装 Chrome 或 Edge

• 一个 Overleaf 账户，免费版即可

• Claude Code（claude --version）或 Claude Desktop

第 1 步：运行设置

在此文件夹中，在 Windows 上：

setup.cmd

在 macOS 或 Linux 上：

./setup.sh

设置会运行五个步骤并逐一打印：

1. 安装依赖

2. 构建到 dist/

3. 检查是否有可用的 Overleaf 会话。如果没有，浏览器窗口会打开 Overleaf 登录页面

4. 读回你的一个真实项目，以证明连接正常

5. 询问是否将服务器注册到 Claude Code

第 2 步：浏览器打开时登录

浏览器窗口是一个真实的 Chrome。像平常一样登录，包括双重验证（2FA）。不会有任何程序替你输入密码，你的密码也绝不会被读取或存储。

一旦你进入项目列表页面，窗口会自动关闭，设置会继续。你的会话 cookie 会保存到 ~/.overleaf-claude-mcp/session.json。

该文件等同于对你 Overleaf 账户的完全访问权限。它已被 git 忽略，并以 0600 权限写入。不要分享它，也不要提交它。

第 3 步：让设置注册服务器

在第 5 步，你会看到一个提示：

      Register this server with Claude Code now? [y/N]

输入 y。这会运行：

claude mcp add overleaf -- node C:/CoolYEAH/overleaf-claude-mcp/dist/index.js

如果你跳过了这一步，或者使用不同的客户端，请手动注册。对于 Claude Code，运行上面的命令。对于 Claude Desktop，在 Windows 上编辑 %APPDATA%\Claude\claude_desktop_config.json，或在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": ["C:/CoolYEAH/overleaf-claude-mcp/dist/index.js"]
    }
  }
}

第 4 步：重启 Claude

MCP 服务器只在启动时加载。退出并重新打开 Claude Code 或 Claude Desktop。

确认它已加载：

claude mcp list

你应该会看到 overleaf 显示为已连接。在 Claude Code 会话中，/mcp 会显示相同的内容。

第 5 步：使用它

直接用自然语言提出请求即可。Claude 会自己选择合适的工具。

List my Overleaf projects

Select the Efficient Reasoning project

Read sections/methodology.tex

In sections/results.tex, change "Table 1" to "Table~\ref{tab:main}"

Compile it and tell me what the LaTeX errors are

Show me figures/fig1.png

Save the compiled PDF to C:/tmp/paper.pdf

选择一个项目后就会固定下来。该选择保存在 ~/.overleaf-claude-mcp/state.json 中，重启后依然有效，因此在你切换之前，之后的每个请求都会应用于该项目。如果不想切换，又希望在一次请求中处理另一个项目，就说出来：“从我的论文项目中读取 main.tex”。

Related MCP server: claudeleaf

如何触发

没有斜杠命令，也不需要输入任何内容。Claude 会读取工具描述，并在你的请求匹配时调用相应的工具。只要提到 Overleaf，或提到你已经选择的项目或文件，就足够了。

如果 Claude 没有调用工具，通常的原因是：注册后没有重启，或者还没有选择项目。可以问“当前选择的是哪个 Overleaf 项目？”来检查。

工具

overleaf_select_project 接受项目 id 或项目名称的任意部分。如果名称匹配多个项目，它会列出候选项目，而不是自行猜测。除非 confirm 为 true，否则 overleaf_delete 会拒绝执行，因此 Claude 不会意外删除文件。

疑难解答

"No Overleaf session at ..." —— 你还没有登录，或者会话已过期。请运行 npm run login，或再次运行 setup.cmd。

Claude 看不到工具 —— 注册后你没有重启 Claude。请运行 claude mcp list 检查。

某个工具突然失败 —— Overleaf 可能更改了某个端点。运行 npm run recon，它会以只读方式探测每个端点，并准确告诉你哪个调用出了问题。

在不使用 Claude 的情况下，从终端检查你的设置：

npm run read -- "Efficient Reasoning"

这会打印匹配项目的文件树和所有章节标题。添加一个路径即可导出单个文件：

npm run read -- "Efficient Reasoning" sections/methodology.tex

随时可以重新运行设置。 它会复用有效的会话并重新验证连接，因此也可以当作健康检查。

工作原理

文件树来自 Overleaf 的 socket 连接，因为那是唯一携带实体 id 的来源，而写入操作需要的就是这些 id。握手请求是 GET /socket.io/1/?projectId=<id>，采用 socket.io 0.9 帧格式；随后服务器会推送 joinProjectResponse，其中包含整个项目，包括 rootFolder、文档 id 和文件哈希。文件树会按 OVERLEAF_TREE_TTL_MS 指定的时长进行缓存（默认 15 秒），并在每次写入后失效。

文本文件按文档逐个读取，因此读取到的始终是当前状态。overleaf_grep 改为读取项目归档，因此搜索整个项目只需一次请求，而不是每个文件一次请求。

写入操作通过上传端点完成。覆盖同名文件的上传属于原地更新：实体 id 会保留，因此 Overleaf 的历史记录以及文档中的其他协作者都能继续正常工作。缺失的父级文件夹会先被创建。

已验证的端点

已在真实账户上实际验证，而非凭空假设：

:type 为 doc、file 或 folder。

脚本

npm run smoke 会创建一个名为 claude-mcp-smoketest 的项目，然后依次执行写入、覆盖、图片上传、重命名、移动、删除和编译操作。它会把项目留在你的账户中，方便你检查。完成后把它删掉即可。

配置

全部可选。参见 .env.example。

限制

这些都不是受支持的 API，Overleaf 随时可能更改它们。请只对你的个人账户使用。尚未实现实时协作编辑：写入操作会替换整个文档，而不是发送字符级操作，因此请避免在其他人正在编辑某个文件时向其中写入。