Overleaf MCP

A real-time Model Context Protocol server for Overleaf — self-hosted Community Edition / Server Pro and overleaf.com. No git-bridge, no fork, no extra infrastructure.

Overleaf MCP lets AI coding agents (Claude Code, Claude Desktop, Codex, Cursor, Continue, and any other MCP-compliant client) read, edit, comment on and compile LaTeX projects on your own Overleaf server or on overleaf.com — and on both at once, from one MCP server (multiple hosts). Instead of going through a git-bridge — a paid feature that Community Edition installs don't have, and one that syncs in batches — it speaks Overleaf's native operational-transform (OT) protocol over Socket.IO, the approach pioneered by Overleaf-Workshop. The agent's edits arrive in the editor as a collaborator's keystrokes: no "file changed externally" toast, and people typing in the same file at the same time are never interrupted.

<p align="center"> <img src="docs/live-coedit-demo.gif" width="502" alt="An agent filling in a list in the Overleaf editor while a person types further down the same file; both sets of changes appear live."> <br> <em>An agent and a person editing the same file at the same time. The person's comment lines are picked up by the agent as <code>&lt;external-changes&gt;</code> and acted on.</em> </p>

Distributed on npm as overleaf-mcp-rt — the rt suffix marks this as the real-time / OT-backed flavor, distinct from git-bridge–style Overleaf MCP servers.

npx overleaf-mcp-rt@latest --help

Table of contents

• Supported Overleaf servers
• Why "real-time"? Native OT vs git-bridge
• Install
• Quick start
• Multiple hosts
• Agent skills
• MCP client config
• Sanity-check: diagnose
• Tools
  • Discovery & read
  • Edit
  • Working alongside humans
  • Comments
  • Project tree CRUD
  • Compile
  • Error envelope
• Changelog
• Roadmap
• FAQ
• Developing
• License
• Acknowledgements

Supported Overleaf servers

| | Self-hosted Community Edition | Self-hosted Server Pro | overleaf.com | |---|---|---|---| | Versions | stock 4.x – 6.x (6.x is the primary target; 3.x and older don't work) | same code base as CE ⁴ | current production | | Read / edit / create / move / delete, live co-editing | ✅ | ✅ | ✅ ¹ | | Compile, read the log, download the PDF | ✅ | ✅ | ✅ | | <external-changes> reports of what people changed | ✅ | ✅ | ✅ | | Review-panel comments | — ² | ✅ | ✅ | | Login | --browser, email + password, or cookie | same | --browser or cookie ³ | | Behind an auth proxy (Cloudflare Access, Basic Auth, …) | ✅ extra headers | ✅ extra headers | n/a |

¹ Projects Overleaf has migrated to its newer history-OT document format can be read (since 2.2.0); editing them is opt-in until it has been verified on overleaf.com — see the FAQ.<br> ² Stock CE has no review panel, so the comment tools return COMMENTS_UNSUPPORTED without changing anything.<br> ³ overleaf.com's password form is CAPTCHA-protected, so email + password login can't work there.<br> ⁴ Server Pro shares CE's real-time and document services and the same review-panel API as overleaf.com, but has not been tested separately — reports welcome.

Nothing is installed on, or changed in, the Overleaf server: the MCP server is just another logged-in client. Live co-editing was verified against Community Edition 6.0.0 and against production overleaf.com with a person typing in the browser throughout — both sides ended byte-identical — and the live test suite runs the server against throw-away instances of CE 4.2, 5.5, 6.0 and 6.3.

Why "real-time"? Native OT vs git-bridge

| | Overleaf MCP (native OT) | git-bridge–style MCP servers | |---|---|---| | Works on Community Edition | ✅ | ❌ (git-bridge is a Server Pro feature) | | Works on overleaf.com | ✅ any plan you can log in to | only on plans with git integration | | Latency to editor | live (per patch, ~100 ms) | minutes (git push + bridge sync) | | Server requirements | none — stock CE 4.x – 6.x, Server Pro, or overleaf.com | Server Pro + git-bridge, or a paid overleaf.com plan | | "File changed externally" toast | never — edits arrive as co-author OT ops | yes — every git sync triggers it | | Someone typing in the same file | both edits survive (OT) | merge conflicts | | Auth model | session cookie | git over HTTPS / token |

Whether your Overleaf runs in Docker on a homelab or is an overleaf.com account, if you want an AI coding agent to edit LaTeX in it with the edits showing up live in the browser, this is the project for you.

Install

# A. Zero-install via npx (recommended for MCP clients)
npx overleaf-mcp-rt@latest --help

# B. Global install for shell use
npm install -g overleaf-mcp-rt
overleaf-mcp-rt --help

Requires Node.js ≥ 20.

As a plugin (MCP server + skills together)

This repository is itself an installable agent plugin: the MCP server wiring plus four agent skills and two slash commands.

| Harness | Install | |---|---| | Claude Code | /plugin marketplace add DanielHou315/overleaf-mcp-rt then /plugin install overleaf-mcp-rt@overleaf-mcp-rt | | Cursor | Add this repository as a plugin marketplace (it ships .cursor-plugin/ manifests and mcp.json), then install overleaf-mcp-rt | | Codex | codex plugin marketplace add DanielHou315/overleaf-mcp-rt then codex plugin add overleaf-mcp-rt@overleaf-mcp-rt (the slash commands arrive as skills) | | Other harnesses | Register the MCP server (see MCP client config) and copy the skills: npx -y overleaf-mcp-rt skills install --target <your skills dir> |

Then log in once from a terminal: npx -y overleaf-mcp-rt login --url <your Overleaf> --browser.

Quick start

# 1. Sign in: opens a browser window, you log in as usual, the session is captured
npx overleaf-mcp-rt login --url https://overleaf.example.com --browser

# 2. Smoke test connectivity, auth, and OT handshake
npx overleaf-mcp-rt diagnose

# 3. List your projects
npx overleaf-mcp-rt ls

Multiple hosts

One server can be logged in to several Overleaf instances at once — say a self-hosted CE box and overleaf.com. Run login once per instance:

npx overleaf-mcp-rt login --url https://tex.example.org                      # first host becomes the default
npx overleaf-mcp-rt login --url https://www.overleaf.com --name overleaf.com # add another (--default to switch the default)
npx overleaf-mcp-rt hosts                                                    # names + URLs, never secrets
npx overleaf-mcp-rt diagnose --host overleaf.com

• A host's name defaults to its hostname without www.; --name overrides it. Logging in again under the same name just refreshes that host's cookie.
• Every MCP tool takes an optional host argument, and overleaf_list_hosts tells the agent what exists. Selection is per call rather than a "current host" switch, so parallel tool calls can't race each other onto the wrong instance. Omit host to use the default. Project ids only mean something on the host they came from.
• Each host has its own session, OT connections and external-change tracking. Hosts are authenticated on first use, and the credentials file is re-read on every call, so you can add or refresh a host while the MCP server is running.
• Credentials live in ~/.config/overleaf-mcp-rt/credentials.json (mode 0600) as { "default": "<name>", "hosts": { "<name>": { url, session_cookie, extra_headers } } }. The single-host file written by earlier versions is still read and is upgraded in place by the next login. OVERLEAF_CREDENTIALS_FILE relocates the file. OVERLEAF_URL / OVERLEAF_SESSION_COOKIE / OVERLEAF_EXTRA_HEADERS still work: they define (or override) the host for that URL and make it the default.
• Browser login (--browser, the default choice at the prompt): Overleaf has no OAuth or device flow for third-party clients, and hosted instances put CAPTCHA, SSO or 2FA in front of the password form — so the login that always works is the real one in a real browser. login --browser launches your installed Chrome / Chromium / Edge / Brave with a throwaway profile (your everyday profile is never touched), opens the instance's login page, and waits. Once you're signed in it reads the session cookie over the DevTools protocol (which, unlike page JavaScript, can see HttpOnly cookies), validates it, saves it, closes the window and deletes the profile. With --url and --browser both given there are no prompts, so it also works from non-interactive runners. OVERLEAF_BROWSER=/path/to/browser picks a specific binary. --cookie and --email remain for headless machines.
• Pasting a cookie: login accepts either the bare value or name=value, and works out whether the instance wants overleaf_session2 (overleaf.com), overleaf.sid (CE ≥ 5) or sharelatex.sid (older CE). Use it where --browser isn't possible (a headless machine): in your browser's devtools open Application → Cookies → https://www.overleaf.com and copy overleaf_session2.

Agent skills

Small, on-demand instructions that teach an agent to use these tools well. They cost a few hundred tokens until one is actually needed.

| Skill | Teaches | |---|---| | overleaf-setup | Installing, logging in (--browser), multiple hosts, diagnose, and what each auth/config error means. | | overleaf-editing | The read → overleaf_edit_doc loop, unique old_strings, small edits, reading <external-changes>, never reverting a human, why to avoid overleaf_write_doc. | | overleaf-latex-workflow | Finding the root file, matching project conventions, compile → read log → fix, leaving the project building, citations and figures. | | overleaf-comments | Comment vs. edit, the required Co-authored by <agent name> signature, replying and resolving, the fallback where comments don't exist. |

Slash commands: /overleaf-login (walks the user through a browser login) and /overleaf-status (hosts, sessions, what to fix).

They are plain SKILL.md folders in skills/, written for any agent — no model- or vendor-specific instructions. Installed with the plugin, or copied anywhere with overleaf-mcp-rt skills install [--target <dir>] (default ~/.claude/skills); overleaf-mcp-rt skills lists them.

MCP client config

Works in Claude Code, Claude Desktop, Cursor, Codex (via MCP), Continue, and any MCP-compliant client.

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "overleaf-mcp-rt@latest"],
      "env": {
        "OVERLEAF_URL": "https://overleaf.example.com",
        "OVERLEAF_SESSION_COOKIE": "overleaf_session2=s%3A..."
      }
    }
  }
}

If your Overleaf is fronted by an authentication proxy (Cloudflare Access, Authelia, oauth2-proxy, HTTP Basic Auth, etc.), pass the proxy headers via the optional `OVE