overleaf-mcp-server

An MCP server that gives an AI agent read, write, compile, and project-management access to your Overleaf projects.

Unofficial. This project is not affiliated with, endorsed by, or supported by Overleaf. It uses Overleaf's undocumented internal web API, which may change or break without notice. If it stops working, that is expected — please open an issue rather than assuming data loss.

Targets MCP specification revision 2026-07-28.

Install

No install needed — npx fetches it on demand. Add this to your MCP client config:

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "overleaf-mcp-server"],
      "env": { "OVERLEAF_SESSION_COOKIE_FILE": "/Users/you/.overleaf-session" }
    }
  }
}

Getting your session cookie

1. Log in to Overleaf in your browser.
2. Open DevTools → Application → Cookies → https://www.overleaf.com.
3. Copy the value of the overleaf_session2 cookie.
4. Save it to a file, e.g. echo 'PASTE_VALUE_HERE' > ~/.overleaf-session && chmod 600 ~/.overleaf-session

The cookie grants full access to your Overleaf account — treat it like a password. A file is preferred over inlining it, since MCP config files are often synced or backed up.

Cookies expire after roughly a few weeks. When that happens, tools fail with a message telling you to re-copy it.

Configuration

| Variable | Required | Purpose | |---|---|---| | OVERLEAF_SESSION_COOKIE | yes* | Value of the overleaf_session2 cookie | | OVERLEAF_SESSION_COOKIE_FILE | yes* | Path to a file containing it (preferred) | | OVERLEAF_BASE_URL | no | Defaults to https://www.overleaf.com | | OVERLEAF_READ_ONLY | no | 1 disables all mutating tools entirely | | OVERLEAF_ALLOW_DESTRUCTIVE | no | 1 permits destructive tools on clients that cannot prompt | | OVERLEAF_ALLOWED_PROJECTS | no | Comma-separated project-ID allowlist | | OVERLEAF_MAX_READ_BYTES | no | read_file size cap, default 1000000 |

* exactly one of the two cookie variables.

Tools

| Tool | What it does | |---|---| | list_projects | List projects (archived/trashed excluded by default) | | list_files | List documents, files, and folders in a project | | read_file | Read a document, including collaborators' unsaved edits | | export_project | Write the whole project to disk as a ZIP | | write_file | Create or overwrite a text document | | upload_file | Upload or overwrite a binary file | | create_folder | Create a folder | | move_entity | Move a file or folder | | delete_entity | Delete a file or folder — confirmation required | | compile_project | Compile and return structured LaTeX diagnostics | | get_compile_log | Return the raw LaTeX log | | get_pdf | Compile and write the PDF to disk | | create_project | Create a new project | | rename_project | Rename a project | | archive_project | Archive a project — confirmation required | | delete_project | Permanently delete a project — confirmation required |

Safety

Destructive tools (delete_entity, archive_project, delete_project) never act on the model's say-so. They return an input_required result so you confirm, and they ignore any confirm argument the model supplies. If your MCP client cannot answer such requests, they refuse until you set OVERLEAF_ALLOW_DESTRUCTIVE=1, which is your standing consent given out-of-band in your own config.

Set OVERLEAF_READ_ONLY=1 and mutating tools are not registered at all — the agent cannot see them, let alone call them.

Troubleshooting

"Overleaf session is not valid (redirected to login)" — your cookie expired. Re-copy overleaf_session2 and update your config.

"Overleaf returned an unexpected shape for …" — Overleaf changed their undocumented API. This error is deliberate: the server refuses to return a plausible-but-wrong answer. Please open an issue with the message.

Compile rate limits — get_compile_log and get_pdf each trigger a fresh compile. Free Overleaf accounts limit compiles aggressively; prefer compile_project's structured diagnostics over repeatedly fetching the raw log.

Development

npm install
npm test          # offline; uses injected fakes, no Overleaf account needed
npm run build
OVERLEAF_SESSION_COOKIE=<real cookie> npm run test:live   # optional, hits real Overleaf

License

MIT