Overleaf MCP PlusPlus

An MCP server that gives agents revision-safe, targeted access to Overleaf projects through Overleaf Git. Agents can inspect small line ranges, search literal text, follow LaTeX document structure across \input and \include, and commit precise edits without rewriting complete files.

Requirements

• Node.js 18 or newer
• An Overleaf plan with Git integration
• An Overleaf project ID and Git token

Install in Claude

Claude Desktop, Claude Code CLI, and the Claude Code VS Code extension can all run the published package through npx. They use different configuration files, described below.

Choose how to provide the Overleaf token

Every configuration needs OVERLEAF_PROJECT_ID and exactly one of the following token variables.

Store the token directly in the MCP configuration:

"env": {
  "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
  "OVERLEAF_GIT_TOKEN": "YOUR_OVERLEAF_GIT_TOKEN"
}

Or, preferably, put only the token in a separate text file and provide its absolute path:

"env": {
  "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
  "OVERLEAF_GIT_TOKEN_FILE": "/absolute/path/to/overleaf-token.txt"
}

The token file may end with a newline; surrounding whitespace is removed when it is read. Do not commit the token or its file. Use an absolute path rather than ~ so the configuration works consistently when launched by a graphical client.

Claude Desktop

Edit the Claude Desktop configuration at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Merge this server into the existing mcpServers object:

{
  "mcpServers": {
    "overleaf-mcp-plusplus": {
      "command": "npx",
      "args": ["-y", "@augustinkr/overleaf-mcp-plusplus@2"],
      "env": {
        "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
        "OVERLEAF_GIT_TOKEN_FILE": "/absolute/path/to/overleaf-token.txt"
      }
    }
  }
}

On Windows, if Claude cannot launch npx directly, use this command form instead:

"command": "cmd",
"args": ["/c", "npx", "-y", "@augustinkr/overleaf-mcp-plusplus@2"]

Completely quit and reopen Claude Desktop after saving the file.

Claude Code CLI and VS Code extension

Claude Code CLI and the Claude Code VS Code extension use the same MCP configuration. For a personal server available in all projects, edit:

• macOS/Linux: ~/.claude.json
• Windows: %USERPROFILE%\.claude.json

Merge this top-level entry into that file:

{
  "mcpServers": {
    "overleaf-mcp-plusplus": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@augustinkr/overleaf-mcp-plusplus@2"],
      "env": {
        "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
        "OVERLEAF_GIT_TOKEN_FILE": "/absolute/path/to/overleaf-token.txt"
      }
    }
  }
}

Install in Codex

Codex CLI and the Codex IDE extension share ~/.codex/config.toml on the same host:

[mcp_servers.overleaf-mcp-plusplus]
command = "npx"
args = ["-y", "@augustinkr/overleaf-mcp-plusplus@2"]
startup_timeout_sec = 30
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

[mcp_servers.overleaf-mcp-plusplus.env]
OVERLEAF_PROJECT_ID = "YOUR_OVERLEAF_PROJECT_ID"
OVERLEAF_GIT_TOKEN_FILE = "/absolute/path/to/overleaf-token.txt"

Restart the Codex client after changing the configuration. OVERLEAF_GIT_TOKEN can be used instead of the token file, but the token-file form avoids storing the secret directly in config.toml.

Run a local checkout

npm install

Point the MCP client directly at the entry point:

{
  "mcpServers": {
    "overleaf-mcp-plusplus-local": {
      "command": "node",
      "args": ["/absolute/path/to/OverleafMCPlusPlus/overleaf-mcp-server.js"],
      "env": {
        "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
        "OVERLEAF_GIT_TOKEN_FILE": "/absolute/path/to/overleaf-token.txt"
      }
    }
  }
}

Configuration

The first matching source wins:

1. OVERLEAF_PROJECT_ID plus OVERLEAF_GIT_TOKEN or OVERLEAF_GIT_TOKEN_FILE
2. OVERLEAF_PROJECTS_CONFIG=/absolute/path/to/projects.json
3. The user configuration file:
   • Windows: %APPDATA%\overleaf-mcp-plusplus\projects.json
   • macOS/Linux: $XDG_CONFIG_HOME/overleaf-mcp-plusplus/projects.json, defaulting to ~/.config/overleaf-mcp-plusplus/projects.json
4. projects.json in the current working directory
5. projects.json beside the installed entry point

Multi-project configuration uses this shape:

{
  "projects": {
    "default": {
      "name": "Main Paper",
      "projectId": "...",
      "gitToken": "olp_..."
    },
    "thesis": {
      "name": "Thesis",
      "projectId": "...",
      "gitToken": "olp_..."
    }
  }
}

Pass projectName to a tool to select a non-default project.

Recommended agent workflow

1. Use list_files to locate the root document and component files.
2. Use compact get_outline, find_text, or read_file_range to locate the relevant content.
3. For an outline node, request detail: "editable" with only its selected occurrenceId. Pass returned spans unchanged to apply_edits or insert_text.
4. Use append_text with a fresh revision for end-of-file or pre-\end{document} insertion.
5. If a mutation returns STALE_REVISION, inspect the affected file again and build a new edit. Never reuse stale spans.

Spans contain opaque offsets, a content hash, the source file, and a revision derived from the exact file content. Agents should not calculate or modify offsets. A mutation is rejected if any target file changed after inspection.

Tools

Project discovery

• list_projects — list configured projects.
• list_files — list synchronized project files, defaulting to .tex.
• status_summary — return a compact file and document-outline summary.

Targeted inspection

• read_file_range — read at most 400 exact, unnumbered lines and receive a reusable span.
• find_text — find literal text with bounded context and match spans.
• get_outline — extract headings, hierarchy, labels, source files, and line locations. It follows literal braced \input and \include directives by default; pass followIncludes: false for one file. Responses are compact by default. To obtain edit spans, call it again with detail: "editable" and up to 20 selected occurrenceIds from the compact response.

Recursive outlines return partial results with warnings when an include is missing, dynamic, ambiguous, cyclic, inaccessible, outside the project, or beyond traversal limits. Logical headings can span several source files, so every outline node identifies its physical source. If one source file is included repeatedly, editing it changes every occurrence.

Mutations

• apply_edits — replace one or more non-overlapping spans, across one or several files, in one commit.
• insert_text — insert verbatim text immediately before or after an inspected anchor span.
• append_text — append at EOF or before the single active \end{document}.
• create_file — create a new path and fail if it already exists.

All mutation tools synchronize first, validate before writing, and push at most one commit. No tool silently normalizes whitespace or line endings.

Examples

To revise one paragraph without reading its complete file:

1. Call find_text with a distinctive phrase.
2. Select the desired match and, if necessary, call read_file_range around its reported lines.
3. Call apply_edits with the returned span and replacement text.

To inspect a split document, call get_outline on main.tex. A heading in sections/methods.tex reports that physical source file even when its logical parent is declared in main.tex. The compact result deliberately omits hashes and offsets. When editing a heading, label, or complete local section, call get_outline again with detail: "editable" and only its selected occurrenceId; this returns headingSpan, labelSpan, and localSectionSpan for that node.

To add material before the document terminator, first call read_file_range to obtain the current revision, then call append_text with destination: "before_end_document".

Migration from v1

Version 2 removes the coarse and ambiguous content tools:

| Removed capability | Replacement | |---|---| | Whole-file read | read_file_range and find_text | | Title-only section listing/read | get_outline plus targeted reads | | Whole-file overwrite | apply_edits, insert_text, or append_text | | Title-based section overwrite | Compact get_outline, then selected editable outline spans plus apply_edits |

There are no deprecated aliases. Clients discover the new tool list after restarting the MCP server.

Development

npm test
npm run check
npm pack

All MCP protocol output is written to stdout. Diagnostics are written to stderr, and credential-bearing Git URLs are masked from surfaced errors.

Security

• The Overleaf Git token grants project read/write access; treat it as a password.
• Prefer OVERLEAF_GIT_TOKEN_FILE where practical.
• Never commit projects.json or token files.
• Tool paths are restricted to the cloned project directory.
• Mutations are marked destructive so supporting MCP clients can request approval.

License

MIT