# overleaf-mcp-server

An MCP server that gives an AI agent read, write, compile, and project-management access to your [Overleaf](https://www.overleaf.com) 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:

```json
{
  "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

```bash
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