overleaf-mcp

An MCP server for Overleaf that lets a Claude or other agent navigate projects, read/edit .tex files, compile, and work with review-panel comments — over Overleaf's real web/Socket.IO API, the same channel the official web editor uses.

The one feature no existing Overleaf MCP can deliver: when a project has track-changes enabled, the agent's edits appear as pending suggestions in the Review panel, the same way a human collaborator's edits do. You and your collaborators can accept or reject each suggestion. You can also ask the agend to accept/reject them (e.g. "accept all suggestions about typos").

Why a new MCP

The three existing Overleaf MCPs (mjyoo2/overleafmcp, YounesBensafia/overleaf-mcp-server, GhoshSrinjoy/Overleaf-mcp) all write through Overleaf's Git bridge, which has two problems for collaborative academic work:

1. Commits show up in Overleaf with delay (the bridge polls).

2. Git-bridge writes bypass tracked changes entirely — even when track-changes mode is on, edits land as direct overwrites, not as suggestions for review.

The overleaf-workshop VSCode extension already uses Overleaf's Socket.IO API rather than Git, but doesn't yet emit tracked changes (issue #94).

overleaf-mcp solves both: a minimal Socket.IO 0.9 client over fetch + ws@8, plus the meta.tc ID seed on applyOtUpdate that flips Overleaf's server-side RangesTracker into track-changes mode.

Related MCP server: arXiv Research Assistant MCP Server

Status

Working end-to-end against overleaf.com — 16 tools, tracked-changes edits and review-panel comments both verified. Published on npm as @netique/overleaf-mcp.

Tools

Typical workflow

Things to ask Claude once overleaf-mcp is connected:

• "Accept every pending tracked change by John Doe that's only adjusting punctuation or whitespace." — uses list_tracked_changes(author_email: "...") → LLM filters by op text → accept_changes(...).

• "List my recent Overleaf projects."

• "Open my thesis project and show me what comments my collaborators have left."

• "Read intro.tex and fix the missing comma in the second paragraph." → with track-changes on, this lands as a tracked suggestion.

• "Compile the project and tell me what the LaTeX errors mean." → uses compile then read_log automatically.

• "For each open comment thread, suggest a fix and reply with what you did." → end-to-end review workflow.

Requirements

• Node ≥ 20

• An Overleaf account (overleaf.com or self-hosted Community Edition)

Quick start

No local install needed — npx fetches and runs the latest version. Add this to your Claude Desktop / Claude Code MCP config:

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "@netique/overleaf-mcp"]
    }
  }
}

The first MCP tool call (or npx @netique/overleaf-mcp login run ahead of time) opens a Chrome window pointed at Overleaf — log in normally and the session cookie is captured and saved to a file under your config dir. No DevTools paste, no cookie in your MCP config. When the cookie expires (~5 days), the next tool call re-opens the window and refreshes it.

For self-hosted Community Edition: set OL_BASE_URL:

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "@netique/overleaf-mcp"],
      "env": { "OL_BASE_URL": "https://overleaf.mylab.edu" }
    }
  }
}

Useful one-shot commands:

npx @netique/overleaf-mcp login              # opens Chrome, captures cookie
npx @netique/overleaf-mcp status             # who am I logged in as
npx @netique/overleaf-mcp logout --confirm   # clear the saved cookie

git clone https://github.com/netique/overleaf-mcp.git
cd overleaf-mcp
npm install
npm run build

Then point your MCP config at the built file:

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

Authentication

The session cookie lives in a plaintext file at <configDir>/overleaf-mcp/cookie.json (mode 0600), where <configDir> is ~/Library/Application Support on macOS, $XDG_CONFIG_HOME (or ~/.config) on Linux, %APPDATA% on Windows. The CSRF token is auto-discovered from the /project page on each session — no separate copy needed.

How the cookie gets there

npx @netique/overleaf-mcp login — or an MCP tool call that finds no stored cookie — spawns Chrome with a dedicated browser profile at <configDir>/overleaf-mcp/chrome-profile/, points it at ${OL_BASE_URL}/project, and reads the session cookie via the Chrome DevTools Protocol once the dashboard loads. Why a dedicated profile:

• We don't touch your real Chrome profile, so there's no macOS Keychain prompt for your everyday browser.

• It's a real interactive Chrome window, so captcha, Google OAuth, ORCID, institutional SSO and 2FA all work out of the box.

• The profile persists. Re-logins are usually a flash: window opens → /project loads → cookie captured → window closes.

When the cookie expires (Overleaf cookies last ~5 days), the next request hits a 302 to /login, overleaf-mcp evicts the stale entry, re-launches Chrome and captures a fresh one. If your browser session also expired, the Chrome window waits for you to log in (up to 5 minutes).

Any Chromium-family browser works — Chrome, Brave, Edge, Arc, Chromium. If findChrome can't locate one automatically, set OL_BROWSER to a binary path.

⚠️ The session cookie grants full account access. The cookie file is mode 0600 but plaintext on disk. Treat it like a password. Remove it with overleaf-mcp logout --confirm.

Environment variables

Troubleshooting

OverleafAuthError: Session cookie rejected (redirected to /login) — your stored cookie has expired. overleaf-mcp relaunches Chrome automatically on the next tool call to refresh; you should only see this surface as a user-facing error if Chrome itself failed to start.

No Chromium-family browser found — install Chrome (or Brave/Edge/Arc/Chromium), or set OL_BROWSER to a binary path.

Socket.IO handshake returned 502 — Overleaf's load balancer rejected the WebSocket upgrade. Usually means the cookie was rejected — overleaf-mcp should auto-recover on the next tool call.

Could not find ol-csrfToken meta tag — your Overleaf server doesn't expose the CSRF meta tag (rare; mostly very old Community Edition). Set OL_CSRF explicitly.

Edits land but don't show up as tracked suggestions — confirm track-changes is on for your user on this project (Menu → Settings → Track Changes → "For me" or "For everyone"). open_project reports the detected state under track_changes_on_for_me. To force tracking regardless, pass track: "on" to edit_file.

Compile succeeds but read_log returns 404 — Overleaf needs ?clsiserverid=... to route to the right CLSI worker; we add this automatically from the previous compile response. If you see this, the previous compile may not have completed; re-run compile and then read_log.

Acknowledgements

• overleaf-workshop by @iamhyc and contributors — protocol reference for the HTTP + Socket.IO flow, comment thread endpoints. The 94-review-panel branch was the source for the comment data shapes.

• overleaf/overleaf — libraries/ranges-tracker/index.cjs and services/document-updater/RangesManager.js are the authoritative source for how tracked changes are emitted (the update.meta.tc flag and ID seed format).

• googlecolab/colab-mcp — UX reference for what an agent-friendly MCP into a hosted editor should feel like.

License

AGPL-3.0-or-later — see LICENSE.

overleaf-mcp incorporates code ported from two AGPL-3.0 projects (overleaf-workshop and overleaf/overleaf — see Acknowledgements), so the combined work is distributed under the same terms. Practical implications:

• You can use, study, and modify overleaf-mcp freely.

• If you redistribute it, modified or not, recipients must also receive the source under AGPL-3.0.

• If you run a modified version as a network service that users interact with, you must make the modified source available to those users. Running unmodified overleaf-mcp as your own personal MCP server is unaffected.