<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. 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 and switch between 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:

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:

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:

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:

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

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

OpenAI Codex CLI

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

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

OpenCode

Add this to opencode.json or ~/.config/opencode/opencode.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:

{
  "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.

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:

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:

%%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:

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

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

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
• Contribution guide
• Outstanding issues

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