Overleaf MCP 服务器

Visualizing the bridge between Overleaf and AI through MCP

"I tried to argue with Overleaf, but it said my syntax was invalid."

Overleaf MCP

A VS Code extension and MCP server for Overleaf. Sign in once, see all your Overleaf projects in a VS Code side panel, open and edit them live, compile and read the PDF right next to your source, sync any project to a local folder, and give AI assistants (anything that speaks the Model Context Protocol) the tools to search, read, edit, and compile your papers — one project or many at a time. 🧠

🔗 Repo: https://github.com/GhoshSrinjoy/Overleaf-mcp · ⬇️ Downloads: latest release

Your Overleaf projects in the side panel, a file open live from Overleaf, and its PDF beside it.

Executive Summary

Version 2 is a rewrite around a single, faster core:

• Live, not polled. The server talks to Overleaf the way the Overleaf editor does: one persistent realtime connection per project. Reading a file takes milliseconds instead of a git pull per call, and edits are applied as small operational-transform updates that merge with whatever collaborators are typing. They show up live in their browser.
• See what you write. Compile on Overleaf and read the PDF in a VS Code tab: it recompiles as the project changes (your saves, collaborators, AI edits), lists errors with links to the line, and jumps between source and PDF with SyncTeX.
• Works on every plan. Signing in with the Overleaf website session needs no paid Git integration and no per-project tokens. Git tokens still work for headless servers (your old projects.json keeps working).
• No infrastructure. Redis and BullMQ are gone. Per-project queues and file locks handle concurrency; the server is a single file you can download and run with Node.js.
• Built for agents. Exact search-and-replace edits, a "suggest mode" that records AI edits as tracked changes for you to accept or reject, ripgrep plus ranked (BM25) search across projects, a LaTeX outline that follows \input, and compile with errors reported as file:line.

In short: Overleaf ⇄ live connection ⇄ VS Code panel + PDF preview + local folders + MCP ⇄ your AI assistant.

Features

VS Code extension

• 📚 Projects panel listing every project (pinned first, then by last update), expandable into its live file tree. Collaborators' file changes appear immediately.
• ✏️ Live editing of Overleaf files (overleaf:// documents): saving pushes your change; edits from collaborators or AI tools reload open files; if a document changed while you edited, your save is merged on top instead of overwriting it.
• 📄 PDF preview next to the editor: Recompile, automatic recompiles on change or on save, draft mode, stop on first error, an errors-and-warnings list that opens the line, zoom, page navigation, download, and SyncTeX both ways (double-click the PDF → source; Show in PDF from the editor).
• 🔁 Local folder sync (two-way): keep a project mirrored in a folder so local LaTeX builds, git and AI file tools work on real files. Edits on both sides merge; true clashes get conflict markers.
• 🩺 Compile problems in the Problems panel, on the Overleaf files and on synced local copies.
• 🔎 Search across projects (the same engine the AI uses).
• 🔐 Sign in with the browser (Google, ORCID, institutional SSO, password, captcha — whatever Overleaf asks), by pasting a session cookie, or with email/password on self-hosted servers.
• 🔌 One-click AI client setup for command-line assistants, desktop apps and editors (list), or every one installed at once, and automatic registration with VS Code's built-in MCP support.

MCP server

21 tools, listed below. It runs inside VS Code, or on its own as a single downloadable file, an npm package, a Claude Desktop bundle, or a Docker image.

Install

Everything is on the latest release. You don't need to clone this repository; that is only for building from source.

VS Code

Download and install in one step:

# Windows (PowerShell)
Invoke-WebRequest https://github.com/GhoshSrinjoy/Overleaf-mcp/releases/latest/download/overleaf-mcp.vsix -OutFile "$env:TEMP\overleaf-mcp.vsix"; code --install-extension "$env:TEMP\overleaf-mcp.vsix"

# macOS / Linux
curl -fsSL -o /tmp/overleaf-mcp.vsix https://github.com/GhoshSrinjoy/Overleaf-mcp/releases/latest/download/overleaf-mcp.vsix && code --install-extension /tmp/overleaf-mcp.vsix

Or without a terminal: download overleaf-mcp.vsix from the latest release, then in VS Code open the Extensions view → … menu → Install from VSIX… and pick the file. If VS Code was already open, run Developer: Reload Window afterwards. (On macOS, if code is not found, run Shell Command: Install 'code' command in PATH in VS Code first.)

Then click the Overleaf icon in the activity bar → Sign in. A browser window opens on the Overleaf login page; log in as usual and it closes by itself. Your projects appear in the panel. To give other assistants access, open the panel menu (…) → Connect an AI Client… and pick one, or Every AI tool found on this computer.

Self-hosted Overleaf (Community Edition / Server Pro)? Run Overleaf: Use a Different Overleaf Server… first.

AI assistants without VS Code

1. Download the server (skip this if you use the VS Code extension: it installs the same file in the same place):

# macOS / Linux
mkdir -p ~/.overleaf-mcp/server && curl -fsSL -o ~/.overleaf-mcp/server/overleaf-mcp.js \
  https://github.com/GhoshSrinjoy/Overleaf-mcp/releases/latest/download/overleaf-mcp.js

# Windows (PowerShell)
New-Item -ItemType Directory -Force "$HOME\.overleaf-mcp\server" | Out-Null
Invoke-WebRequest https://github.com/GhoshSrinjoy/Overleaf-mcp/releases/latest/download/overleaf-mcp.js -OutFile "$HOME\.overleaf-mcp\server\overleaf-mcp.js"

2. Add it to your assistant:

On Windows (PowerShell), use the full path and quote the -- (PowerShell drops a bare -- before it reaches these tools):

claude  mcp add --scope user overleaf '--' node "$HOME\.overleaf-mcp\server\overleaf-mcp.js"
codex   mcp add overleaf '--' node "$HOME\.overleaf-mcp\server\overleaf-mcp.js"
copilot mcp add overleaf '--' node "$HOME\.overleaf-mcp\server\overleaf-mcp.js"

3. Sign in. Ask the assistant to sign in to Overleaf (the sign_in tool opens the Overleaf login page in your browser), or do it once from a terminal: node ~/.overleaf-mcp/server/overleaf-mcp.js login --browser. The session is saved in ~/.overleaf-mcp/credentials.json and shared by every assistant on the computer.

With npx instead: use npx -y https://github.com/GhoshSrinjoy/Overleaf-mcp/releases/latest/download/overleaf-live-mcp.tgz as the command (for example claude mcp add --scope user overleaf -- npx -y <that URL>). On Windows, clients that cannot start npx themselves need cmd /c npx -y <that URL>.

From source

Only needed if you want to change the code or build the files yourself:

git clone https://github.com/GhoshSrinjoy/Overleaf-mcp.git
cd Overleaf-mcp
npm install
npm run package                      # creates overleaf-mcp-<version>.vsix
code --install-extension overleaf-mcp-2.1.0.vsix
npm run package:release              # all release files into build/release

PDF preview

Right-click a project → Open PDF Preview, or click the preview button at the top of an open .tex file. The preview opens beside the editor.

• Recompile (or Ctrl+Enter / ⌘+Enter in the preview) compiles on Overleaf with the project's own compiler and main document. While the preview is open it also recompiles by itself:

  • On any change (default): your saves, collaborators' edits and AI edits.
  • When you save: only your saves in VS Code (Overleaf files and synced local copies).
  • Never: only when you press Recompile.

  Pick one under the arrow next to Recompile, or with the overleafMcp.pdf.autoCompile setting. A preview in a background tab catches up when you show it.

• Draft mode (faster, leaves images out) and Stop on first error are in the same menu.

• Errors and warnings are counted in the toolbar; click the count for the list, and an entry to open its line. They are also in the Problems panel.

• SyncTeX: double-click anywhere in the PDF to open the source line that produced it. In the editor, right-click → Show in PDF highlights where the cursor's line ended up. Both also work for projects synced to a local folder.

• Zoom (also Ctrl + mouse wheel), page number, Save the PDF…, Open in your PDF viewer, the raw compile log, and find (Ctrl+F).

SyncTeX: the paragraph under the cursor, highlighted in the PDF.

When to recompile, draft mode and stop on first error.

An error from Overleaf's compile: underlined at its line, listed in the preview (click to jump) and in the Problems panel.

To give Show in PDF a shortcut, add to keybindings.json:

{ "key": "ctrl+alt+j", "command": "overleafMcp.syncToPdf", "when": "resourceScheme == overleaf" }

Connecting AI clients

The extension installs a stable copy of the server at ~/.overleaf-mcp/server/overleaf-mcp.js (it survives extension updates) and shares your sign-in with it through ~/.overleaf-mcp/credentials.json. Connect an AI Client… writes the configuration for you:

Pick one assistant, or set up every one found on the computer.

Stdio servers work with or without VS Code running. The HTTP endpoint shares the extension's live connections, so its edits show up in open editors instantly. More client-specific notes are in CLAUDE_CONFIG.md.

MCP Tools

Every tool accepts a project by name, id or Overleaf URL, and every file in a project can be read, searched and changed. Errors explain how to recover (for example, an ambiguous oldText reports how many times it occurs; a near miss shows the passage that differs only in whitespace).

Overleaf documents cannot contain emoji or other characters outside the Basic Multilingual Plane; tools reject such edits with the offending line instead of letting Overleaf corrupt them.

Local folder sync

Right-click a project → Sync to Local Folder… (default ~/Overleaf/<project>). The folder must be new or empty.

• Saving a file locally pushes it within a second; edits on Overleaf are written to the file.
• Changes made while sync was off are reconciled three ways (local / Overleaf / last synced): one-sided changes are copied, edits on both sides are merged, and clashing edits get <<<<<<< markers. Resolve and save; the resolution is pushed.
• Build output (*.aux, *.log, the main PDF, …) stays local; edit .overleafignore in the folder to change that.
• The PDF preview, Show in PDF and compile problems work on the local copies too.
• Only one VS Code window (or CLI) syncs a folder at a time; another takes over if it closes.
• Without VS Code: overleaf-mcp sync "<project>" [folder].

Headless, CLI and Docker

The server is a single self-contained file (overleaf-mcp.js on the release page, dist/mcp-server.js when built; Node ≥ 20). From npm it is called overleaf-live-mcp.

overleaf-mcp                         serve MCP over stdio (what AI clients launch)
overleaf-mcp --http [--port N]       serve MCP over HTTP on 127.0.0.1
overleaf-mcp login --browser         sign in on the real login page
overleaf-mcp login --cookie <value>  or paste the overleaf_session2 cookie
overleaf-mcp login --email E --password P   (self-hosted servers)
overleaf-mcp status | logout
overleaf-mcp sync <project> [folder] two-way sync until Ctrl+C

(overleaf-mcp stands for node path/to/overleaf-mcp.js.)

Docker (your existing client config docker compose run --rm -T mcp keeps working):

docker compose build
docker compose run --rm mcp login --cookie "<overleaf_session2 value>"   # optional: web session
docker compose run --rm -T mcp                                         # what MCP clients run

The compose file mounts projects.json (Git tokens) and ./data (session, caches, Git clones). Without a session, projects listed in projects.json are served through the Git bridge:

{
  "projects": {
    "default": { "name": "My Paper", "projectId": "YOUR_PROJECT_ID", "gitToken": "YOUR_GIT_TOKEN" }
  }
}

Git-token projects support reading, searching, outlines, edits (commit + push, retried if someone pushed first) and history. Compile, suggest mode and project listing need the web session.

Environment variables

Methodology

                    ┌──────────────── Overleaf (overleaf.com or self-hosted) ────────────────┐
                    │  web API (projects, zip, uploads, compile, SyncTeX, history)   realtime │
                    └───────────────▲────────────────────────────────────────▲────────────────┘
                                    │ session cookie                          │ OT updates, live events
┌──────────────────────── core (TypeScript) ──────────────────────────────────┴──────────────┐
│ SessionBackend ── realtime pool (1 connection/project, auto-reconnect)    GitBackend (tokens) │
│ OverleafService: project resolution · pins · snapshot cache · ripgrep / BM25 search          │
│                  LaTeX outline · log parser · 3-way merge · local mirror engine              │
└───────────────▲───────────────────────────────▲───────────────────────────────▲─────────────┘
                │                               │                               │
     MCP server (stdio / HTTP)          VS Code extension                CLI (sync, login)
     AI assistants                      panel · overleaf:// files ·      Docker image
                                        PDF preview (pdf.js) ·
                                        local sync · problems

1. Sign-in. A throwaway browser profile opens the real Overleaf login page; once you are in, the session cookie is captured over the DevTools protocol and the profile is deleted. Cookies live in VS Code's secret storage, mirrored (optionally) to an owner-only file for MCP servers started by other apps.
2. Reading. Documents are read over the realtime connection (always the latest text, including unsaved typing of collaborators). Search uses a local text snapshot per project, refreshed only when Overleaf reports the project changed.
3. Writing. Edits become OT updates against the version that was read; the server transforms them over concurrent edits. Overleaf's newer history-ot documents are supported, including tracked changes.
4. Compiling. Compiles run on Overleaf's own servers. The preview draws the PDF with pdf.js inside a locked-down webview; SyncTeX lookups go to Overleaf with the id of the build on screen, so positions always match the PDF you see. Edits arriving over the realtime connection trigger debounced recompiles, one at a time per project.
5. Concurrency. Per-project queues in-process, file locks across processes, and a lease for local sync folders.

Security notes

• ~/.overleaf-mcp/credentials.json holds the Overleaf session (owner-only permissions). Turn off overleafMcp.mcp.shareSessionWithExternalClients to keep it only in VS Code's secret storage.
• Signing out also ends the session on Overleaf when it was created by the browser or password sign-in; a pasted cookie is left alone (it is your browser's session).
• The HTTP endpoint listens on 127.0.0.1 only, requires a bearer token, and rejects browser (cross-origin) requests.
• The PDF preview runs only its own scripts (strict content security policy); scripts inside PDFs are not run, and links open through VS Code's usual confirmation.
• Git tokens are passed to git through its environment, never written to .git/config or shown in process lists.
• projects.json, data/ and *.vsix are git-ignored. Never commit tokens.

Development

npm install
npm run build          # dist/extension.js, dist/mcp-server.js and the PDF viewer files in media/pdfjs
npm run typecheck
npm test               # unit tests
npm run package:server # build/release: overleaf-mcp.js, overleaf-live-mcp.tgz, overleaf-mcp.mcpb
npm run package:release  # the same plus overleaf-mcp.vsix
npm run screenshots    # retake the README screenshots (needs the local Overleaf below)

Integration tests run against a local Overleaf Community Edition in Docker (nothing touches overleaf.com):

docker compose -f test/overleaf-ce/docker-compose.yml up -d    # first start takes a minute
npm run test:integration    # protocol and SyncTeX, live editing (both doc formats), MCP end to end, browser sign-in, Git mode, local sync
npm run test:extension      # inside a real VS Code instance: panel, live files, PDF preview, SyncTeX, auto-recompile, MCP endpoint, sync
npm run test:vsix           # the same, against the packaged .vsix as installed

If port 8090 is taken, start the server with OVERLEAF_TEST_PORT=8095 and run the tests with OVERLEAF_TEST_URL=http://localhost:8095.

Press F5 in VS Code to launch an Extension Development Host.

Troubleshooting

• "Not signed in … or the session has expired" — sign in again from the panel, or ask your assistant to use sign_in (sessions expire after a few days without use).
• Browser sign-in doesn't open — set overleafMcp.browserPath to Chrome, Edge, Brave or Chromium, or use Paste a session cookie.
• The PDF preview stays empty — check Output → Overleaf MCP; Show Compile Log shows what LaTeX said. A compile that times out on Overleaf usually finishes in draft mode.
• "Too recently compiled" — Overleaf refuses compiles less than a second or two apart; the extension and the compile tool wait and retry.
• Long compiles time out in Codex — raise tool_timeout_sec for [mcp_servers.overleaf] in ~/.codex/config.toml (the default is 60 seconds).
• Port 39847 in use — change overleafMcp.mcp.httpServer.port; stdio clients are unaffected.
• "Overleaf asked for a captcha" — password sign-in is blocked on overleaf.com; use the browser sign-in.
• Rate limited — Overleaf limits logins (10 per 2 minutes), project downloads (10 per minute per project) and compiles; the tools back off and retry.

Citation

If you use this software in your research, please cite:

@software{overleaf_mcp_2025,
  author = {GhoshSrinjoy},
  title = {Overleaf MCP Server},
  year = {2025},
  url = {https://github.com/GhoshSrinjoy/Overleaf-mcp}
}

Next Steps

🧾 Comments and review threads as MCP tools. 📦 Publish to the VS Code Marketplace and to npm (npx -y overleaf-live-mcp). 🧠 Optional semantic (embedding) search on top of BM25. 🗂️ Project-wide find-and-replace with preview.

MIT License