overleaf-mcp

Let your coding agent (Claude Code, Cursor, Codex CLI, Windsurf, Claude Desktop, …) work on your Overleaf projects: list projects, read and write .tex/.bib files, compile, read the LaTeX log, download the PDF.

Built for our team Overleaf at overleaf.yihome.org (API at https://github.yihome.org/api/v1, used by default). Works with any self-hosted Overleaf running the overleaf-selfhost companion API — set OVERLEAF_API_URL to point elsewhere. (overleaf.com has no such API.)

Using an AI coding agent? Paste this repo's URL to it and say "install this MCP server". The agent should follow llms-install.md, which contains everything it needs.

What you need

1. An API key — sign in at https://github.yihome.org with your Overleaf account → API keys → Create key. Copy it once; it's shown only once. Tip: create a separate Overleaf account for your AI and share only the projects it should touch, then make the key from that account.

2. (Only for other deployments) the API URL, shaped like https://github.<domain>/api/v1, passed as OVERLEAF_API_URL.

Related MCP server: Unofficial Overleaf MCP Server

Install (one command per client)

No clone, no build — npx fetches and runs it straight from GitHub.

Claude Code

claude mcp add overleaf -s user -e OVERLEAF_API_KEY=olk_... -- npx -y github:yidong72/overleaf-mcp

Codex CLI (~/.codex/config.toml)

[mcp_servers.overleaf]
command = "npx"
args = ["-y", "github:yidong72/overleaf-mcp"]
env = { OVERLEAF_API_KEY = "olk_..." }

Cursor (.cursor/mcp.json in the project, or ~/.cursor/mcp.json) / Windsurf (~/.codeium/windsurf/mcp_config.json) / Claude Desktop (claude_desktop_config.json) — same JSON shape:

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "github:yidong72/overleaf-mcp"],
      "env": { "OVERLEAF_API_KEY": "olk_..." }
    }
  }
}

Verify (any shell):

OVERLEAF_API_KEY=olk_... npx -y github:yidong72/overleaf-mcp --check
# → OK: connected to ... as you@example.com (key "..."); 3 project(s) visible

Tools

Typical agent loop: list_projects → read_file main.tex → write_files (small edits) or upload_files (whole files from disk) → compile (read the log on failure, fix, repeat) → download_pdf → optionally github_push.

Speed note: write_files makes the model generate the file as tokens (a 200 KB .bib ≈ 50K tokens). upload_files reads the bytes locally and sends them straight to the API, so large or binary files transfer in seconds.

The GitHub tools need the user to have linked their GitHub account and the project to a repository once in the sync web UI (the same place API keys are made); until then they return a 409 explaining what to do.

Notes

• Writes are whole-file replacements applied atomically; Overleaf users editing the same file in the browser see a "changed externally" notice.

• The API acts with exactly the permissions of the account that made the key.

• The full REST API this wraps is documented at https://<your api host>/api/v1/docs and, for agents, /api/v1/llms.txt.

• Requires Node.js ≥ 18 (for fetch and npx).

• Different Overleaf deployment? Add -e OVERLEAF_API_URL=https://github.<domain>/api/v1 (or the same key in the JSON env).

License

MIT