<p align="center">
  <img src="docs/overleafmcp-logo.png" alt="Overleaf MCP" width="220">
</p>

# Overleaf MCP

Overleaf MCP lets an AI agent work with your Overleaf projects through the
[Model Context Protocol](https://modelcontextprotocol.io/). The agent can find
and read LaTeX, suggest edits, compile the project, inspect errors, and view the
rendered PDF without leaving its normal coding environment.

Every source edit is submitted as a tracked-change suggestion. You remain in
control and accept or reject the changes in Overleaf.

> [!IMPORTANT]
> The project owner needs an Overleaf plan that supports tracked changes. The
> MCP never falls back to direct editing when tracked changes are unavailable.

## What it can do

- List joined projects and pending invitations, accept an invitation, and switch projects.
- Search and read live LaTeX sources without downloading whole files.
- Read review comment threads together with their source anchors.
- Add, replace, revise, or withdraw tracked suggestions.
- Follow concurrent human edits through Overleaf's live document channel.
- Compile in draft or clean mode and report errors and warnings.
- Render PDF pages and download project assets to local artifact paths.
- Route document tasks to multiple named agents.

Reviewer accounts cannot create files or accept suggestions. If an agent needs
a new file, `create_file` tells it to ask you to create the empty file first.

## Install

Python 3.11 or newer is required. `pipx` is recommended because it exposes the
MCP commands globally while keeping their dependencies isolated:

```bash
pipx install --include-deps "overleaf-mcp[login]"
playwright install chromium
```

The Playwright dependency is used only for the one-time browser login. The MCP
server itself runs headlessly.

To install from a source checkout instead:

```bash
git clone https://github.com/ayghri/overleaf-mcp.git
cd overleaf-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[login]"
python -m playwright install chromium
```

On Windows, activate the environment with `.venv\Scripts\activate`.

## Authenticate with Overleaf

Run the login command once on a machine with a display:

```bash
overleaf-mcp-login
```

A Chromium window opens. Sign in and complete any captcha. The session is saved
under `~/.local/state/overleaf-mcp/auth/` and reused by the MCP server. Run the
login command again when the session expires.

No configuration file is required for overleaf.com. For a self-hosted instance
or optional login-form prefill, create
`~/.config/overleaf-mcp/config.toml`:

```toml
base_url = "https://www.overleaf.com"
email = "bot@example.com"
password = "optional-login-prefill"
```

A dedicated Overleaf account invited as a reviewer is recommended. The MCP
still forces tracked suggestions if the account has broader permissions.

## Connect an agent

Overleaf MCP is a standard local stdio server. Give each running agent a unique
`--agent-id` so its cursor, suggestions, and assigned tasks are identifiable.

### Claude Code

```bash
claude mcp add overleaf -s user -- overleaf-mcp --agent-id writer
claude mcp list
```

### OpenAI Codex CLI

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.overleaf]
command = "overleaf-mcp"
args = ["--agent-id", "writer"]
```

### OpenCode

Add this to `opencode.json` or `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "overleaf": {
      "type": "local",
      "command": ["overleaf-mcp", "--agent-id", "writer"],
      "enabled": true
    }
  }
}
```

### Other MCP clients

Claude Desktop, Cursor, Cline, Windsurf, and similar clients accept the usual
local-server JSON:

```json
{
  "mcpServers": {
    "overleaf": {
      "command": "overleaf-mcp",
      "args": ["--agent-id", "writer"]
    }
  }
}
```

If the client cannot find `overleaf-mcp`, use the executable's absolute path.
Restart the client after changing its MCP configuration.

## Start using it

Ask the agent to initialize the workflow and select a project:

> Use the Overleaf MCP. Call `workflow_help`, list my projects, and select the
> project named KATA.

`list_projects` labels each result as `joined` or `pending`. Use
`accept_project_invite` with a pending project id before selecting it.

After selection, ordinary requests are enough:

- “Find the expressivity section and tighten the first paragraph.”
- “Compile cleanly and show me the remaining warnings.”
- “Render page 4 so we can inspect the table.”
- “Show my pending suggestions in `main.tex`.”

The usual edit flow is `search`, a bounded `read_file`, `goto_text`, and an edit
operation. Suggestions stay pending until you accept them in Overleaf.

The selected project persists for that agent. You can optionally pin a default
project in `~/.config/overleaf-mcp/agents/writer.toml`:

```toml
project_id = "your-overleaf-project-id"
```

Use `overleaf-mcp --list-agents` to see live agent ids and their selected
projects.

## Optional document task inbox

An agent can wait for work addressed to its id in LaTeX comments:

```latex
%%bot: writer
%%todo: rewrite this paragraph
Text the agent should work on.
%%end bot: writer
```

The agent uses `wait_for_command`, `claim_command`, and `complete_command` to
move the task from `todo` to `doing` to `done`. These comments do not appear in
the compiled PDF.

## Docker

Perform the browser login on the host, then build the runtime image:

```bash
overleaf-mcp-login
docker build -t overleaf-mcp .
```

Run the image as the MCP client's stdio command, mounting the saved session:

```bash
docker run -i --rm \
  -v ~/.config/overleaf-mcp:/config:ro \
  -v ~/.local/state/overleaf-mcp/auth:/session:ro \
  overleaf-mcp --agent-id writer
```

Use absolute mount paths in clients that do not perform shell expansion.

## Troubleshooting

- **Authentication expired:** run `overleaf-mcp-login` again.
- **No project selected:** ask the agent to call `list_projects` and
  `select_project`.
- **Agent id already running:** choose another `--agent-id` or inspect
  `overleaf-mcp --list-agents`.
- **Client cannot start the server:** run `overleaf-mcp --agent-id test` in a
  terminal to expose the startup error.
- **A non-BMP character is rejected:** the legacy Overleaf editing endpoint does
  not safely preserve characters such as emoji in source mutations.

## Development and design

- [Architecture and safety invariants](docs/ARCHITECTURE.md)
- [Contribution guide](docs/CONTRIBUTING.md)
- [Outstanding issues](issues.md)

```bash
poetry install --with dev
poetry run ruff check overleaf_mcp tests
poetry run pytest
```