# overleaf-connect

An MCP server to have agents use Overleaf for free.

Once it's connected, an agent can:

- create or duplicate projects
- list, read, write, and edit `.tex` files
- compile a project and pull the PDF back locally

## Installation

If you dont have `uv` installed, [install it](https://docs.astral.sh/uv/getting-started/installation/).

It needs your Overleaf session cookie to do anything, so grab that first:

1. Sign in at [overleaf.com](https://www.overleaf.com/project).
2. Open DevTools -> **Network**, reload the project list, click any `overleaf.com` request, and copy the full `Cookie` **request header**.

Copy over this for the `OVERLEAF_SESSION` environment variable in the MCP server.

### Claude Code

```bash
claude mcp add overleaf -e OVERLEAF_SESSION="overleaf_session2=s%3A...; GCLB=..." -- uvx overleaf-connect
```

### Claude Desktop

Open **Settings -> Developer -> Edit Config** and add an `overleaf` entry under `mcpServers` (keep any servers you already have):

```json
{
  "mcpServers": {
    "overleaf": {
      "command": "uvx",
      "args": ["overleaf-connect"],
      "env": {
        "OVERLEAF_SESSION": "overleaf_session2=s%3A...; GCLB=..."
      }
    }
  }
}
```

Afterwards, restart Claude Desktop to reload the MCP servers and get Overleaf connected.

## Authentication

Overleaf issues a fresh cookie on every request. After the first success the
server saves the rotating value to:

- Windows: `%LOCALAPPDATA%\overleaf-connect\session.json`
- macOS / Linux: `~/.overleaf-connect/session.json`

The `OVERLEAF_SESSION` environment variable is treated as a seed - the server will automatically refresh the session whenever requests are done to Overleaf, and store it. You only need to change it in the future if the cookie has expired from not using it.

### Optional environment variables

```text
OVERLEAF_SESSION_FILE=...  # where the rotating session cookie is cached
OVERLEAF_CACHE_DIR=...     # compiled-PDF cache
OVERLEAF_OUTPUT_DIR=...    # allowed download_pdf destination root
                          # (default: ~/Downloads/overleaf-connect, or
                          #  ~/Documents/overleaf-connect, else ~/overleaf-connect)
```

## Tools

| Tool | What it does |
|---|---|
| `status` | check if session cookie works |
| `list_projects` | id, name, owner email, last updated |
| `create_project` | blank project |
| `duplicate_project` | clone an existing project |
| `list_files` | paths in a project |
| `read_file` | text contents of a file (`full=true` for files over 100k chars) |
| `write_file` | whole-file create/replace |
| `edit_file` | exact old/new string replace in a file |
| `compile_project` | Overleaf compile -> cached `output.pdf` + parsed errors |
| `download_pdf` | compile and copy the PDF under `OVERLEAF_OUTPUT_DIR` |
| `trash_project` | move a project to Overleaf trash |

Writes replace the whole file, so `write_file` refuses to write back a file that
was only read in part - read it again with `full=true`, or use `edit_file`.
Don't edit a file while someone is typing in it in the browser.