# Overleaf MCP

Read and edit Overleaf projects from Claude, using the Overleaf git bridge.

> WARNING: When your provide the MCP with a project ID, This gives Claude access to the ENTIRE project directory.

## Requirements

- Overleaf premium (check your institution's access!)
- `uv`, `git`, TeX distribution, and `pdftocairo` (you could `brew install poppler` on Macs)

## Setup

1. Clone this repo.

2. Create `~/.overleaf-mcp/projects.json`. An example is in `projects.json.example`. 
   ```json
   { "default": "paper", "projects": { "paper": "<project-id>" } }
   ```

3. Add the server to your Claude config. You can generate the git token in Overleaf Account
   Settings.

   ```json
   {
     "mcpServers": {
       "overleaf": {
         "command": "/absolute/path/to/uv",
         "args": ["run", "--directory", "/absolute/path/to/overleaf-mcp", "overleaf-mcp"],
         "env": { "OVERLEAF_TOKEN": "your_git_token" }
       }
     }
   }
   ```

4. Restart your Claude Desktop. 

## How it works

A project is `unverified` until `open_project` succeeds, which checks that
every `\usepackage` resolves against your local TeX environment, and baseline-compiles each root.

> All writes are refused until open_project passes

A `.tex` containing `\documentclass` is a _root_, while _children_ are included with 
by `\input`/`\include`/`\subfile`. Editing a child re-compiles the roots that include
it. For instance, this covers a standard `main.tex` + `sections/` project, a single-file paper, or even a
folder of standalone one-page documents with the same rule.
Further, any errors block a push while warnings are only reported.

## Tools

| tool | description |
|---|---|
| `open_project` | pull, verify environment, and baseline-compile  |
| `files` | list `.tex`, marking roots |
| `outline` | structure with line numbers |
| `read` | line-numbered, optionally a range (`lines="150-190"`) |
| `grep` | regex search, `file:line: match` |
| `edit` | replace an exact unique snippet, compile-gated |
| `write` | create or overwrite a whole file |
| `write_section` | create or overwrite one section, using the exact title |
| `add_asset` | copy an image or binary |
| `compile` | compile the owning root, return a digest |
| `render` | one page as an image - very useful for layout/images |