overleaf-mcp

What it is

A local Model Context Protocol server that gives Claude five tools for working with an Overleaf project: list_projects, list_files, read_file, edit_file, sync. Every change goes through Overleaf's per-project Git remote, so the round-trip is Claude → MCP server → git push → Overleaf web UI.

What it is not

• Not a replacement for Overleaf

• Not a hosted multi-user service. Single researcher, single Claude session, stdio transport.

• Not a LaTeX compiler. Overleaf still does the rendering.

• No branch / merge / diff tooling. Use git directly for that.

• No real-time collaboration with humans editing in the Overleaf web UI at the same moment (use Overleaf's native real-time collab for that; the MCP server pulls before every write to stay honest, but doesn't subscribe to live updates)

If those constraints feel restrictive, that's deliberate. See the project notes for the design rationale.

Requirements

• Python 3.11 or newer

• A paid Overleaf account (Git integration is a paid feature)

• An Overleaf Git authentication token: Overleaf web UI → Account Settings → Git Integration → New token

• git on your PATH

• git config user.name and git config user.email set globally (the server signs commits with this identity)

Install

pipx install overleaf-mcp-server

or with uv:

uv tool install overleaf-mcp-server

Either gives you the overleaf-mcp command.

Quick start

Interactive setup

# 1. Configure a project alias
overleaf-mcp init
#   Project alias (short nickname): my-paper
#   Overleaf project ID: 5f4a...           # from the project URL on overleaf.com
#   Display name (optional): My Paper

# 2. Store your Overleaf token in the OS keychain
overleaf-mcp auth add --project my-paper
#   Overleaf token: ****                    # paste, hidden input

# 3. Clone the project locally (one-time)
git clone https://git.overleaf.com/<project_id> ~/.cache/overleaf-mcp/my-paper

# 4. Verify
overleaf-mcp doctor

Scripted setup (v0.1.2+)

For provisioning scripts and CI, every prompt above has a flag-based equivalent:

# 1. Configure non-interactively (--alias engages non-interactive mode)
overleaf-mcp init \
    --alias my-paper \
    --project-id 5f4a... \
    --display-name "My Paper"
# add --force to overwrite an existing alias without prompting

# 2. Store the token via stdin (preferred: keeps it off the process command line)
printf '%s' "$OVERLEAF_TOKEN" | overleaf-mcp auth add --project my-paper --token-stdin

# or read from a named environment variable
overleaf-mcp auth add --project my-paper --token-from-env OVERLEAF_TOKEN

# 3. Clone the project (same as interactive)
git clone "https://x:${OVERLEAF_TOKEN}@git.overleaf.com/<project_id>" \
    ~/.cache/overleaf-mcp/my-paper

# 4. Verify
overleaf-mcp doctor

There is intentionally no --token VALUE flag. Values on the command line leak via ps; pipe through stdin or use an env var instead.

doctor prints a clean pass/fail report. If everything is green you're ready to wire up Claude Desktop.

Claude Desktop configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

{
  "mcpServers": {
    "overleaf": {
      "command": "overleaf-mcp",
      "args": ["serve"]
    }
  }
}

Fully quit and relaunch Claude Desktop (cmd-Q on macOS, since closing the window isn't enough). In a new conversation, ask Claude something like "use overleaf list_projects" to verify.

Remote deployment (HTTP, for claude.ai web)

If you want to use the server with claude.ai web or any other MCP client that can't spawn local subprocesses, run it as an HTTP server. Same tools, different transport.

Required: a strong bearer token. The server refuses to start without OVERLEAF_MCP_AUTH_TOKEN set, because it would otherwise expose every Overleaf token in your keychain to anyone who can reach the bound port.

# Generate a token
export OVERLEAF_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"

# Run on loopback (default; safe for local-only access)
overleaf-mcp serve-http

# Or bind public + put a TLS-terminating reverse proxy in front
overleaf-mcp serve-http --host 0.0.0.0 --port 8080

Endpoints:

• POST /mcp/: the MCP endpoint. Requires Authorization: Bearer <token>. Trailing slash matters.

• GET /healthz: monitoring. Returns {"status": "ok"} with no auth.

In claude.ai's connector settings, point at https://your-host/mcp/ and set the bearer token. claude.ai handles the rest.

Security checklist before exposing publicly:

• TLS via reverse proxy (nginx, caddy, cloudflare). The server speaks plain HTTP.

• Strong token. openssl rand -hex 32 is good; anything shorter is not.

• Rotate the token whenever it leaks. Update OVERLEAF_MCP_AUTH_TOKEN and restart.

• Consider IP allowlisting at the proxy if your access pattern is fixed.

Tools

For concrete usage prompts and recipes, see EXAMPLES.md.

Troubleshooting

When something doesn't work, run overleaf-mcp doctor first. It diagnoses most setup problems and prints the exact command to fix them. Common cases beyond that:

For HTTP-transport deployment beyond local use, see the recipes under docs/deployment/: Caddy, nginx, and Fly.io walkthroughs.

GitHub mirror (optional)

The MCP server only knows about your Overleaf remote. If you want a GitHub backup of a project, add it as a second remote on the local clone:

cd ~/.cache/overleaf-mcp/my-paper
git remote add github git@github.com:you/my-paper-mirror.git
git push github main

Then git push github main whenever you want to update the mirror, or wire up a cron / launchd job. The MCP server intentionally doesn't manage GitHub. That boundary keeps the server's surface small and the mirror under your control.

Security

• Tokens are stored in the OS keychain (keyring library: macOS Keychain, Windows Credential Manager, libsecret on Linux). Never on disk.

• The config file (~/.config/overleaf-mcp/config.toml) contains aliases and project IDs only. No secrets. Safe to put under version control if you really want to.

• Subprocess git invocations pass tokens via env vars consumed by a transient GIT_ASKPASS script. Tokens never appear on the subprocess command line, so they don't show in ps.

• The server only talks to git.overleaf.com and the local filesystem. No telemetry, no analytics, no other network traffic.

Limitations

• Regex section parser. Handles \section, \subsection, \subsubsection (and starred variants) at the start of a line. Doesn't follow \input{} / \include{} across files, doesn't expand custom section macros, and doesn't parse titles with nested {} groups. Swap-in of a pylatexenc-backed parser is staged behind the abstract base class for a future minor release.

• Single-user assumption. No locks, no concurrent-edit detection beyond git pull --ff-only (which fails fast if the local clone has diverged). Real-time collaboration with humans editing in the Overleaf web UI works because the server pulls before every write, but it's not a streaming sync.

• stdio transport only in v0.1. HTTP/SSE for remote / multi-client setups is staged for v0.2.

• No clone orchestration. doctor reports if the local clone is missing and prints the git clone command; the MCP server itself doesn't create or refresh the cache. Plain git is the right tool there.

Contributing

Bug reports and PRs welcome. See CLAUDE.md for project-local design notes if you're working on the server itself.

License

MIT. See LICENSE.