Overleaf Mcp

overleaf-forge

[](https://www.npmjs.com/package/overleaf-forge) [](#license)

A Model Context Protocol server that lets an AI assistant (Claude Code, Claude Desktop, or any MCP client) read, edit, compile, and verify an Overleaf project over Overleaf's built-in git integration. The model edits a local clone with surgical, conflict-safe operations and pushes to Overleaf; nothing depends on scraping the web UI.

> Acknowledgement. Forked from mjyoo2/OverleafMCP, the original Overleaf MCP server. This fork adds conflict-safe editing, binary/figure upload, a clean-build PASS/FAIL gate, citation and voice linting, snapshots, a bootstrap for recurring structured documents, per-project contexts, and a hardened git layer (no-shell execFile, credential-helper auth, error redaction).

Why

Editing a LaTeX project through an AI normally means one of two bad options: paste files back and forth by hand, or let the model overwrite whole files and hope it didn't clobber an edit you made in the browser. This server removes both. It treats Overleaf's git remote as the source of truth and gives the model anchored edits (replace an exact string, refuse if it moved), a conflict gate (a stale or concurrent change is detected, never silently overwritten), and a build verdict (compile from scratch, PASS only on zero errors and zero undefined references), so an editing session is safe to run unattended and provable when it's done.

Token economy

Safety is one motivation; keeping a large document out of the model's context window is the other, and it drove most of the tool design. A 50 KB chapter is about 12K to 13K tokens, so the cost of a naive workflow is dominated by moving that whole file in and out.

Rough token cost per operation on such a chapter, and the cut each tool buys:

| Operation (on a ~50 KB chapter) | Whole-file workflow | overleaf-forge | Reduction | | --- | --- | --- | --- | | One surgical edit | ~25K (read + write the file) | ~0.15K (edit_file) | ~99% | | A dozen edits (one revision pass) | ~170K | ~3K | ~98% | | One compile check | ~1.5K (raw latexmk log) | ~0.02K (verify_build verdict) | ~99% | | Locating a passage | ~13K (read the whole file) | ~2K (get_section_content / search_text) | ~85% |

Figures are order-of-magnitude, for a chapter this size; the absolute numbers scale with file size, the percentages roughly hold.

• Anchored edits instead of whole-file rewrites. Changing one phrase by reading the whole file and writing it back costs roughly 25K tokens per edit: the file into context, then the file back out as the write payload. edit_file sends only the old and new strings and returns a one-line confirmation, on the order of 100 tokens. Across a dozen edits to a single chapter that is the difference between roughly 170K tokens and 3K.
• A one-line build verdict instead of a raw log. verify_build returns ✓ PASS — 24 pages rather than the latexmk output. A raw log runs to hundreds or thousands of tokens per compile, and a multi-pass log buries the true final state under transient undefined-reference warnings from early passes (the exact trap verify_build classifies away by reading the final log). Over a session of repeated compiles that is a few thousand tokens against a few dozen.
• Section and grep reads instead of the whole file. get_section_content returns one section and search_text returns the matching lines, so locating something costs 1K to 3K tokens rather than the full 13K.

For an iterative edit, build, and review loop on a large document the tool traffic runs about an order of magnitude lighter than a read-and-rewrite-the-whole-file approach. The gain is workflow-dependent: a single full-file rewrite is a wash, since write_file moves the same bytes either way. It is the repeated, surgical work that compounds, which is exactly the shape of writing and revising a paper.

Features

• Surgical, conflict-safe edits: edit_file replaces an exact anchor and refuses if the region changed on Overleaf; non-overlapping concurrent edits auto-merge via git.
• No silent clobbering: full-file write_file requires a freshness token (baseSha) or an explicit overwrite to replace an existing file.
• Binary / figure upload: push PNG/PDF figures from disk (single or a whole set in one commit), byte-exact, path-confined to the project.
• Build verification: verify_build compiles from scratch with latexmk and returns PASS/FAIL on the real "done" bar (a PDF, zero errors, zero undefined references/citations) with the page count.
• Citation tooling: append BibTeX entries with duplicate-key protection; lint for undefined and unused citations.
• Section-aware reading: list sections and pull a single section's body by title.
• Project grep: search_text over tracked files.
• Snapshots: checkpoint a rollback point before a risky edit; restore it as a forward commit (no force-push, no history rewrite).
• Recurring-document bootstrap: one call to clone, register, and scaffold a new instance of a structured document (see [Bootstrap](#bootstrap-for-recurring-structured-documents)).
• Per-project context: durable notes and writing guidelines surfaced to the model at the start of a session.
• Hardened git layer: every subprocess runs through execFile (no shell), the token is supplied via an environment-backed credential helper and never appears in a command or an error, and tokenized URLs are redacted from any error returned.

Requirements

• Node.js ≥ 18 (ESM).
• git on PATH.
• A LaTeX distribution with latexmk (only for compile_file / verify_build; the rest works without it). The default engine is LuaLaTeX; latexmk is expected at /Library/TeX/texbin (MacTeX) or otherwise on PATH.
• An Overleaf account with Git integration enabled (a paid feature at time of writing).

Install

Recommended: npx. Nothing to clone, nothing to keep updated by hand. The whole install is a few lines of JSON in your MCP client, plus two values from Overleaf.

1. Get your two values: an Overleaf git token (Account Settings → Git Integration → create token) and your project id (the ` in https://www.overleaf.com/project/`).
2. Add this block to your client's config file (locations in the table below):

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "overleaf-forge@latest"],
      "env": {
        "OVERLEAF_GIT_TOKEN": "olp_xxxxxxxxxxxxxxxxxxxxxxxx",
        "OVERLEAF_PROJECT_ID": "0123456789abcdef01234567"
      }
    }
  }
}

1. Restart the client (or reload its MCP servers). That's it.

npx fetches and runs the published package on demand. The token and project id are the entire setup for a single project, with no config file (this is env-only mode). @latest means each client restart picks up the newest published version automatically; pin overleaf-forge@2.7.1 instead to freeze a version. For multiple projects, per-project contexts, or the SSA bootstrap, see [Configuration](#configuration).

An MCP server is not an app you launch yourself: the client starts it as a subprocess, so "installing" it just means making its command available to the client. The npx form above needs no install step. If you would rather have a real command on your PATH, install it globally:

npm install -g overleaf-forge

and set "command": "overleaf-forge" with no args (keep the same env block). A global install does not auto-update: refresh it yourself with npm update -g overleaf-forge. npx is recommended precisely because it skips that step.

To hack on the server instead, run it from source:

git clone https://github.com/nomanfoundhere/overleaf-mcp.git
cd overleaf-mcp
npm install

Then use "command": "node", "args": ["/absolute/path/to/overleaf-mcp-server.js"] in the client config in place of the npx form.

Wiring into specific clients

The mcpServers schema is identical across clients; only the file location differs. Put the npx block above inside each.

| Client | Config file | | --- | --- | | Claude Code | ~/.claude.json | | Claude Desktop | claude_desktop_config.json (Settings → Developer → Edit Config) | | LM Studio | ~/.lmstudio/mcp.json (or the app's Edit mcp.json) | | Cursor and others on the Cursor mcp.json convention | their mcp.json |

Restart the client (or reload its MCP servers) after editing, so it spawns the server with the new config.

Updating

As a user. With overleaf-forge@latest in your config (the recommended form), restart the client or reload its MCP servers and it fetches the newest published version. If you pinned a version (overleaf-forge@2.7.1), change the number. If npx seems to keep running an old version, clear its cache with npx clear-npx-cache and restart. If you installed globally instead, update with npm update -g overleaf-forge.

As the maintainer (publishing a new release). From the repository:

npm version patch        # or minor / major; bumps package.json and tags
npm publish              # enter your npm 2FA one-time code when prompted
git push --follow-tags   # push the commit and the version tag

Anyone on @latest picks the new version up on their next client restart.

Configuration

Two modes, smallest first.

Env-only mode (one project, no files)

Set OVERLEAF_GIT_TOKEN and OVERLEAF_PROJECT_ID in the client's env block (as in Install). The server builds a single default project from them and lands clones under ~/.overleaf-mcp/repos/. This covers the common single-project case completely.

| Env var | Meaning | | --- | --- | | OVERLEAF_GIT_TOKEN | Overleaf git token. Required, here or in projects.json. | | OVERLEAF_PROJECT_ID | The id from https://www.overleaf.com/project/. Its presence triggers env-only mode. | | OVERLEAF_PROJECT_NAME | Optional display name for the synthesized project. | | OVERLEAF_MCP_HOME | Optional. Override the data home (default ~/.overleaf-mcp). | | OVERLEAF_MCP_TEMPLATES | Optional. Override the templates directory. | | OVERLEAF_VOICE_LINTER | Optional. Prose-linter command for voice_lint (alternative to settings.voiceLinter). |

Config-file mode (multiple projects, contexts, bootstrap)

For more than one project, per-project contexts, or the SSA bootstrap, use a projects.json. Scaffold it:

npx overleaf-forge init

That creates ~/.overleaf-mcp/projects.json from the example and copies the editable templates into ~/.overleaf-mcp/templates/. You can fill in the settings conversationally instead of by hand: ask the assistant to set up overleaf-forge and it runs the configure tool (which asks where your templates, voice linter, and course folders live, then writes them). Or edit the file directly:

{
  "settings": {
    "gitToken": "olp_xxxxxxxxxxxxxxxxxxxxxxxx",
    "repoDir": "/Users/you/Overleaf"
  },
  "projects": {
    "default": {
      "name": "My Paper",
      "projectId": "0123456789abcdef01234567",
      "cwd": "/Users/you/path/where/you/run/the/client"
    }
  }
}

| Setting | Meaning | | --- | --- | | settings.gitToken | Overleaf git token, used by every project (or set OVERLEAF_GIT_TOKEN). A per-project gitToken overrides it. | | settings.repoDir | Where project clones land by default (repoDir/). A per-project localPath overrides it. | | settings.templatesDir | Optional. Directory of scaffold templates, overriding the bundled defaults. | | settings.voiceLinter | Optional. A prose-linter command (or set OVERLEAF_VOICE_LINTER) that voice_lint runs on a file. Defaults to the bundled examples/voice-lint.mjs; override with your own house style. | | projects..projectId | The id from https://www.overleaf.com/project/. | | projects..cwd | Directory you launch the client from for this project; used to auto-detect the active project. | | projects..localPath | Explicit clone location (optional). |

projects.json is re-read on every call, so registering a project or rotating the token takes effect immediately, with no restart. (Code changes do need a restart; the server loads its .js once at startup.)

Where files live

User state (the projects.json, per-project contexts/, customised templates/, and the git clones) lives in the data home, resolved as: $OVERLEAF_MCP_HOME if set, else the package directory when it already holds a projects.json (so an existing local clone keeps working untouched), else ~/.overleaf-mcp. Bundled, read-only defaults (the templates and the stock writing-guidelines) ship inside the package; a copy you place in the data home overrides the bundled one.

Getting Overleaf credentials

1. Git token: Overleaf → Account Settings → Git Integration → create a token. One token covers every project on the account.
2. Project ID: the id segment of the project URL: https://www.overleaf.com/project/.

Per-project context (optional but recommended)

Assignment-specific notes (terminology, deadlines, structure constraints, pinned decisions) live in contexts/.md under the data home, and shared writing rules in writing-guidelines.md. Both are re-read on every get_context call, so you can edit them mid-session. get_context is the intended first call of a writing session.

Customising the templates

The SSA bootstrap scaffolds from two templates: main.tex (the document skeleton) and context-scaffold.md (the project-questions checklist). Defaults ship with the package. To change them, run npx overleaf-forge init (which copies both into ~/.overleaf-mcp/templates/) and edit them in place, or point settings.templatesDir / OVERLEAF_MCP_TEMPLATES at your own directory. The tokens __SSA_NAME__, __SSA_TITLE__, __SSA_DATE__, and __OVERLEAF_READ_URL__ are substituted at scaffold time. A missing template falls back to the built-in default, so a partial templates directory never breaks the bootstrap.

Install via an AI agent

Hand this to an agent (Claude Code, Cursor, etc.) to set up the server in the current client:

Install the Overleaf MCP server (npm package: overleaf-forge).
1. Find this client's MCP config file (Claude Code ~/.claude.json, Claude Desktop's
   claude_desktop_config.json, or LM Studio ~/.lmstudio/mcp.json).
2. Add an "overleaf" entry under mcpServers:
     command: "npx", args: ["-y", "overleaf-forge"]
   with an env block containing OVERLEAF_GIT_TOKEN and OVERLEAF_PROJECT_ID.
3. Ask me for my Overleaf git token (Account Settings → Git Integration) and the
   project id from my project URL. Do not invent them.
4. For multiple projects or the SSA bootstrap, run `npx overleaf-forge init`
   and edit ~/.overleaf-mcp/projects.json instead of the env block.
5. Tell me to restart or reload MCP servers in the client, then call status_summary
   to confirm it connected.

Quick start

A typical editing session, in the model's words:

1. "Read the context for this project." → get_context
2. "Show me the sections in Chapters/ch2.tex." → get_sections
3. "In Chapters/ch2.tex, change \section{Intro} to \section{Introduction}." → edit_file (anchored, conflict-safe)
4. "Add a figure: upload ~/plots/fig1.png to figures/fig1.png." → upload_file
5. "Verify the build." → verify_build → ✓ PASS — 12 pages

Every write commits and pushes to Overleaf; verify_build is the gate before calling the work done.

Conflict safety

Edits never silently overwrite a concurrent Overleaf change.

• edit_file pulls the latest first (so a non-overlapping browser edit is absorbed), then replaces an exact anchor string. If the anchor is gone, the region changed since you read it, and the edit refuses rather than guessing. On the rare push race, git per

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nomanfoundhere
• Source: nomanfoundhere/overleaf-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.