Skip to main content
Glama

OverleafMCP

Autonomous Overleaf Workflows for AI Coding Agents

Create Overleaf projects from local folders, upload .tex papers & figures, sync via Git Bridge, and run self-healing remote PDF builds — on both Free and Paid Overleaf accounts.

CI Latest Release Python 3.11 | 3.12 | 3.13 MCP Tools Overleaf Free & Paid License: MIT

⚡ 30-Sec Install · 🔐 Auth Picker · 📋 Copy-Paste Prompts · 🧠 How It Works · 🧰 13 Tools · ❓ FAQ


✨ Why OverleafMCP?

Overleaf has no public REST API, and community Git-only MCP servers break on Free Overleaf accounts, cannot list your projects automatically, cannot create new projects, and cannot compile PDFs or read LaTeX error logs.

OverleafMCP unifies Web Session and Git Bridge under a single 13-tool MCP server:

Capability

Manual Browser

Git-Only MCPs

🍃 OverleafMCP (Hybrid)

Works on Free Overleaf accounts

✅

❌ (Paid only)

✅ Yes (Browser / Cookie)

Works with Permanent Git Tokens (olp_...)

❌

✅

✅ Yes (Transient Basic Auth)

Auto-discover & resolve projects by Title or URL

Manual

❌ (Hardcoded IDs)

✅ overleaf_list_projects

Bootstrap brand-new project from local folder / .zip

Drag & drop

❌

✅ overleaf_create_project

Upload binary figures (.pdf, .png) & nested folders

Manual

❌ (Text only)

✅ overleaf_upload_folder

Remote PDF Compile + Structured output.log Parser

Manual click

❌

✅ overleaf_compile

Self-hosted Overleaf CE / Institutional Server Pro

✅

Partial

✅ Custom host & git_host


Related MCP server: overleaf-mcp-server

⚡ 30-Second Install (Choose Your Agent)

TIP

One-time prerequisite: Install uv (brew install uv on macOS, or curl -LsSf https://astral.sh/uv/install.sh | sh) so uvx runs overleaf-mcp directly from GitHub with zero manual cloning.

Click your AI coding tool below to expand copy-ready instructions:

Option A — One-liner terminal command:

codex mcp add overleaf -- uvx --from git+https://github.com/ajmainapon/OverleafMCP overleaf-mcp

Option B — Add to ~/.codex/config.toml (Codex uses TOML, not JSON):

[mcp_servers.overleaf]
command = "uvx"
args = ["--from", "git+https://github.com/ajmainapon/OverleafMCP", "overleaf-mcp"]
startup_timeout_sec = 30.0

# Optional: pass credentials via env instead of configuring in chat
# [mcp_servers.overleaf.env]
# OVERLEAF_COOKIE = "overleaf_session2=s%3A..."
# OVERLEAF_GIT_TOKEN = "olp_..."

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "overleaf": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ajmainapon/OverleafMCP",
        "overleaf-mcp"
      ]
    }
  }
}
claude mcp add overleaf -- uvx --from git+https://github.com/ajmainapon/OverleafMCP overleaf-mcp

Open your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "overleaf": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ajmainapon/OverleafMCP",
        "overleaf-mcp"
      ]
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project workspace):

{
  "mcpServers": {
    "overleaf": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ajmainapon/OverleafMCP",
        "overleaf-mcp"
      ]
    }
  }
}

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "overleaf": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ajmainapon/OverleafMCP",
        "overleaf-mcp"
      ]
    }
  }
}
git clone https://github.com/ajmainapon/OverleafMCP.git
cd OverleafMCP
uv sync

Point your MCP client's command directly to /absolute/path/to/OverleafMCP/.venv/bin/overleaf-mcp with empty args: [].


🔐 Connect Your Overleaf Account

Not sure which auth mode to pick? Use this quick guide:

  • Using Chrome or Firefox on Free/Paid Overleaf? -> Expand Mode A (zero copy-paste!)

  • Using Safari, Arc, Brave, or a remote Linux server? -> Expand Mode B (paste overleaf_session2)

  • Have Overleaf Paid / Student / Institutional plan? -> Add Mode C (permanent olp_... Git token)

  1. Sign into overleaf.com in Chrome or Firefox.

  2. Send this prompt to your agent:

    Check my Overleaf authentication status and list my projects.
  3. (macOS first-run) Click Always Allow if Keychain asks permission to read your browser cookie.

  1. Open overleaf.com -> open DevTools (Cmd+Option+I or F12).

  2. Navigate to Application (or Storage) -> Cookies -> https://www.overleaf.com.

  3. Copy the value of overleaf_session2 (begins with s%3A...).

  4. Paste it directly to your agent in chat:

    Save my Overleaf cookie: s%3A...

    (Saved locally with 0600 user-only permissions at ~/.config/overleaf-mcp/credentials.json.)

  1. Open Overleaf Account Settings -> Git Integration -> Create Token.

  2. Tell your agent:

    Save my Overleaf Git token: olp_...

All environment variables override ~/.config/overleaf-mcp/credentials.json when set:

Variable

Default

Description

OVERLEAF_COOKIE

(Browser auto-load)

overleaf_session2=s%3A... (or bare s%3A... value, or "browser").

OVERLEAF_GIT_TOKEN

None

Overleaf Git Bridge token (olp_...) from Account Settings.

OVERLEAF_HOST

www.overleaf.com

Overleaf web domain (set to your self-hosted domain for Overleaf CE/Pro).

OVERLEAF_GIT_HOST

git.overleaf.com

Overleaf Git host (auto-derived from OVERLEAF_HOST when omitted).

OVERLEAF_MCP_CONFIG_DIR

~/.config/overleaf-mcp

Directory storing credentials.json (0600).

OVERLEAF_MCP_GIT_DIR

~/.cache/overleaf-mcp/repos

Cache directory for Git Bridge checkouts.


📋 Copy-Paste Prompt Playbook

Click the copy icon in the top-right corner of any prompt below and drop it straight into your agent:

Create a new Overleaf project called "NeurIPS 2027 Submission" from ./paper, compile it on Overleaf, and download the compiled PDF to ./neurips_draft.pdf.
Upload my local sections/ folder to my Overleaf project "NeurIPS 2027 Submission", run overleaf_compile, inspect any errors or undefined citations in diagnostics, fix them in the .tex files, and re-compile until there are 0 errors.
Upload all PDFs and PNGs inside ./experiments/plots to the figures/ folder of https://www.overleaf.com/project/<YOUR_PROJECT_ID> and recompile the paper.
Pull the latest files from my Overleaf project "NeurIPS 2027 Submission" into ./paper-latest and summarize what changed in main.tex.

🧠 Architecture & Self-Healing Compile Loop

flowchart LR
    subgraph Agents["🤖 AI Coding Clients"]
        A1["OpenAI Codex"]
        A2["Google Antigravity"]
        A3["Claude Code / Desktop"]
        A4["Cursor / VS Code"]
    end

    MCP["🍃 OverleafMCP<br/>(13 Stdio Tools)"]

    subgraph Engines["⚡ Hybrid Transport Layer"]
        W["🍪 Web Session Client<br/>• Free & Paid Accounts<br/>• CSRF + Socket.IO<br/>• Create / Upload / Compile"]
        G["🌿 Git Bridge Client<br/>• Paid & Institutional<br/>• Transient HTTP Basic Auth<br/>• Clone / Diff / Rebase / Push"]
    end

    OL[("📄 Overleaf Cloud<br/>& Self-Hosted")]

    Agents <-->|"JSON-RPC (stdio)"| MCP
    MCP --> W
    MCP --> G
    W <-->|"HTTPS + WSS"| OL
    G <-->|"Git Smart HTTP"| OL
sequenceDiagram
    actor User as Researcher
    participant Agent as AI Agent
    participant MCP as OverleafMCP
    participant OL as Overleaf CLSI Compiler

    User->>Agent: "Upload method.tex, compile, and fix any LaTeX errors"
    Agent->>MCP: overleaf_upload_file("method.tex")
    MCP->>OL: POST /project/{id}/upload (CSRF)
    Agent->>MCP: overleaf_compile(project)
    MCP->>OL: POST /project/{id}/compile
    OL-->>MCP: status="failure" + output.log URL
    MCP->>OL: GET output.log
    MCP-->>Agent: diagnostics.errors: ["! Undefined control sequence l.84"]
    Agent->>MCP: overleaf_write_file("method.tex", patched_tex)
    Agent->>MCP: overleaf_compile(project, save_pdf_path="./paper.pdf")
    MCP->>OL: POST /project/{id}/compile + GET output.pdf
    MCP-->>Agent: status="success", error_count=0, saved "./paper.pdf"
    Agent-->>User: "Fixed macro typo on line 84 — compiled PDF saved!"

🧰 Complete Tool Explorer (13 Tools)

Every project tool accepts a 24-character Project ID, a full Overleaf project URL, or an exact Project Title.

Tool

Key Parameters

Auth

Description

overleaf_auth_status

verify_live: bool = True

Both

Verifies Web Session & Git Token validity and counts accessible projects.

overleaf_configure_auth

cookie, git_token, host, git_host

Both

Writes credentials/hosts to ~/.config/overleaf-mcp/credentials.json (0600).

overleaf_list_projects

include_archived, include_trashed

Web

Lists projects with id, name, access_level, last_updated, and editor_url.

Tool

Key Parameters

Auth

Description

overleaf_create_project

project_name, source_path=None, template="none"

Web

Creates blank/example project or auto-zips & uploads a local directory/.zip (with automatic folder-upload fallback).

overleaf_upload_file

project, local_path, remote_path=None

Web

Uploads any text or binary file (.tex, .bib, .pdf, .png) and creates missing parent folders.

overleaf_upload_folder

project, local_dir, remote_dir="", method="auto"

Hybrid

Uploads a directory tree via Web API ("web") or Git Bridge ("git" / "auto"), skipping .git, .DS_Store, *.aux, etc.

overleaf_write_file

project, remote_path, content

Web

Creates or overwrites a UTF-8 file directly in Overleaf from memory.

overleaf_delete_path

project, remote_path

Web

Deletes a remote file or directory inside a project.

Tool

Key Parameters

Auth

Description

overleaf_list_files

project

Web

Lists the full hierarchical tree of folders, doc text entities, and binary file entities.

overleaf_read_file

project, remote_path, save_to_path=None

Web

Reads .tex/.bib content as UTF-8 text or saves binary files locally.

overleaf_pull_project

project, output_dir, method="zip"

Hybrid

Downloads & extracts an entire Overleaf project via .zip ("zip") or Git ("git").

overleaf_compile

project, save_pdf_path=None, draft=False, root_doc_path=None

Web

Runs Overleaf's remote LaTeX compiler, parses errors/warnings from output.log, and saves output.pdf.

overleaf_git_sync

action (clone|pull|status|push), project_id, local_dir

Git

Direct Git Bridge operations with automatic pull --rebase conflict recovery.


🛡️ Security & Reliability Highlights

IMPORTANT

Bothoverleaf_session2 cookies and olp_... Git tokens grant read/write access to your Overleaf projects — never commit them to version control.

  • User-Only 0600 Credential Vault: overleaf_configure_auth stores secrets at ~/.config/overleaf-mcp/credentials.json (chmod 600).

  • Zero Plaintext Tokens in .git/config: Git Bridge calls inject transient git -c http.extraHeader="Authorization: Basic ..." headers per invocation and scrub tokens from error output.

  • Deterministic WebSocket Cleanup: Fixes pyoverleaf's Socket.IO connection leak by guaranteeing socket.close() inside finally blocks across long multi-step sessions.

  • Strict Stdio Isolation: Browser keyring/cookie loaders redirect stdout -> stderr so third-party warnings never corrupt JSON-RPC framing in strict clients like Codex.

  • Zip-Slip Traversal Defense: Archive extraction enforces Path.is_relative_to() containment against .. and sibling-prefix attacks.


❓ Interactive Troubleshooting FAQ

Overleaf browser session cookies (overleaf_session2) expire periodically or when you sign out. Open overleaf.com in Chrome/Firefox to refresh your login, or paste a fresh overleaf_session2 cookie in chat (Save my Overleaf cookie: s%3A...).

On the first uvx invocation, uv resolves and caches dependencies (~5–10s). Set startup_timeout_sec = 30.0 under [mcp_servers.overleaf] in ~/.codex/config.toml (subsequent launches take ~150ms), or run from a local clone .venv/bin/overleaf-mcp.

Overleaf restricts git.overleaf.com to Paid, Student/Institutional, and Server Pro plans. On a Free account, use overleaf_create_project, overleaf_upload_file, overleaf_upload_folder(..., method="web"), overleaf_pull_project(..., method="zip"), and overleaf_compile — all of which work on Free accounts!

Overleaf's .zip project importer rejects archives without a .tex root file (HTTP 422). overleaf_create_project automatically catches this and falls back to creating a blank project and uploading your directory tree file-by-file!


🧪 Local Development & CI Tests

git clone https://github.com/ajmainapon/OverleafMCP.git
cd OverleafMCP
uv sync
uv run python tests/test_server.py

Released under the MIT License · Built by Ajmain Istiak Apon

⬆ Back to Top

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers