Overleaf Community Edition MCP Server & REST Bridge 🚀

A native Model Context Protocol (MCP) server and REST API bridge specifically built for self-hosted Overleaf Community Edition (ShareLaTeX).

Connect AI coding assistants and agents (Claude Desktop, Cursor, Antigravity, Windsurf) directly to your private Overleaf instance to explore, read, live-edit, patch, and compile LaTeX documents with real-time browser synchronization and automated log diagnosis.

⚡ Why Overleaf Community Edition Needs This

Overleaf Community Edition (CE) is the go-to self-hosted solution for academic labs, universities, and privacy-conscious researchers. However:

1. No Public API or Git Sync: Overleaf reserves official REST APIs and Git integration (git.overleaf.com) for paid Cloud plans and Server Pro licenses.

2. The Operational Transformation (OT) Trap: Overleaf manages live editing in-memory and Redis through document-updater. Editing documents directly in MongoDB corrupts active sessions or gets overwritten.

3. No Automated Compilations for AI: Existing community MCP tools only do local Git commits—they cannot trigger the server-side TeX Live engine (clsi), parse LaTeX compile errors, or return the resulting PDF.

What overleaf-ce-mcp does differently:

• ✅ 100% Native to Community Edition: Works out of the box with standard sharelatex/sharelatex Docker deployments (tested on CE v5 & v6).

• ✅ OT-Safe & Real-Time Sync: Files written or patched through this bridge pass through Overleaf's upload pipeline. Connected browser tabs immediately see changes live on screen via WebSockets without disconnecting or corrupting the document.

• ✅ Server-Side LaTeX Compilation: Compiles projects using your instance's TeX Live environment (pdflatex, xelatex, lualatex).

• ✅ Structured Error & Warning Extraction: Automatically parses LaTeX .log files and extracts exact line numbers, error messages, and context snippets so your AI agent can auto-debug its own LaTeX code.

• ✅ Direct PDF Delivery: Generates authenticated URLs and streaming endpoints for instant PDF preview and download.

• ✅ Protected & Dual Protocol: Protected by Authorization: Bearer <API_KEY>, exposing both MCP (Streamable HTTP /mcp & SSE /sse) and a clean REST API.

Related MCP server: Unofficial Overleaf MCP Server

📐 Architecture

flowchart LR
    subgraph Client["Your Local Machine"]
        AI["AI Assistant (Antigravity / Claude / Cursor)"]
    end

    subgraph Server["Your Server (Docker Network)"]
        Bridge["overleaf-ce-mcp (:8000)"]
        Overleaf["Overleaf Web (:80 / :3000)"]
        DocUpdater["document-updater (:3003)"]
        CLSI["CLSI / TeX Live (:3013)"]
        Redis[("Redis (:6379)")]
        Mongo[("MongoDB (:27017)")]
    end

    AI -- "MCP / REST (Bearer Auth)" --> Bridge
    Bridge -- "Session Injection" --> Redis
    Bridge -- "Project Metadata" --> Mongo
    Bridge -- "OT-Safe Upload / Sync" --> Overleaf
    Overleaf <--> DocUpdater
    Overleaf <--> Redis
    Overleaf -- "Compile LaTeX" --> CLSI
    DocUpdater <--> Mongo

🛠️ MCP Tools Reference

When connected, your AI assistant receives the following tools:

🚀 Quick Start (Docker Compose)

1. Add overleaf-mcp to your Overleaf docker-compose.yml

In your existing Overleaf deployment directory (where docker-compose.yml or Overleaf Toolkit resides), add the overleaf-mcp service:

services:
  # ... your existing overleaf, overleaf-mongo, overleaf-redis services ...

  overleaf-mcp:
    image: ghcr.io/alanmagno1/overleaf-ce-mcp:latest
    container_name: overleaf-mcp
    restart: unless-stopped
    mem_limit: 256m
    depends_on:
      overleaf:
        condition: service_started
      overleaf-mongo:
        condition: service_healthy
      overleaf-redis:
        condition: service_started
    ports:
      # Expose on your desired host port:
      - "8099:8000"
    environment:
      # Generate a secure key: openssl rand -hex 32
      OVERLEAF_MCP_API_KEY: "your-secret-api-key-here"

      # Internal Docker URLs (match your existing service names):
      OVERLEAF_WEB_URL: "http://overleaf:80"
      OVERLEAF_API_URL: "http://overleaf:3000"
      OVERLEAF_MONGO_URL: "mongodb://overleaf-mongo:27017/sharelatex?replicaSet=overleaf"
      OVERLEAF_REDIS_URL: "redis://overleaf-redis:6379/0"

      # Base URLs used to format PDF download links in compile outputs:
      OVERLEAF_PUBLIC_BASE_URL: "https://overleaf.example.com/mcp-bridge"
      OVERLEAF_TAILSCALE_BASE_URL: "http://your-server-ip:8099"
    networks:
      - default
      - overleaf-net

2. Start the service

docker compose up -d overleaf-mcp

3. Verify Health

curl http://localhost:8099/api/health
# {"status":"ok","service":"overleaf-ce-mcp"}

🌐 Exposing Over HTTPS (Reverse Proxy / Cloudflare Tunnel)

If your Overleaf instance is published behind a domain (e.g. https://overleaf.example.com), you can route /mcp-bridge/ to the bridge container.

Option A: Via Overleaf's Internal Nginx

Add this snippet to /etc/nginx/vhost-extras/overleaf/mcp-bridge.conf (or mount it in your compose file):

location ^~ /mcp-bridge/ {
    resolver 127.0.0.11 valid=5s ipv6=off;
    set $mcp_upstream http://overleaf-mcp:8000;
    proxy_pass $mcp_upstream;

    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Connection "";

    # Critical for SSE (Server-Sent Events) and compilations:
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
    proxy_read_timeout 10m;
    proxy_send_timeout 10m;
}

location = /mcp-bridge {
    return 308 /mcp-bridge/;
}

Reload Nginx:

docker exec overleaf nginx -s reload

Option B: Via Caddy

overleaf.example.com {
    handle /mcp-bridge/* {
        reverse_proxy overleaf-mcp:8000 {
            flush_interval -1
        }
    }
    handle {
        reverse_proxy overleaf:80
    }
}

💻 Client Configuration

Antigravity (~/.gemini/antigravity/mcp_config.json)

{
  "mcpServers": {
    "overleaf": {
      "serverUrl": "https://overleaf.example.com/mcp-bridge/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-api-key-here"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

Using mcp-remote to bridge Streamable HTTP to Claude Desktop's stdio:

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://overleaf.example.com/mcp-bridge/mcp",
        "--header",
        "Authorization: Bearer your-secret-api-key-here"
      ]
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "overleaf": {
      "url": "https://overleaf.example.com/mcp-bridge/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-api-key-here"
      }
    }
  }
}

📡 REST API Reference

All REST endpoints accept Authorization: Bearer <API_KEY>, X-API-Key: <API_KEY>, or query param ?api_key=<API_KEY>.

• GET /api/health: Health status (public).

• GET /api/projects: List all projects with metadata.

• GET /api/projects/{id}/files: Get full folder tree and flat file/doc indices.

• GET /api/projects/{id}/file?path_or_doc_id=main.tex: Read doc content in real time.

• POST /api/projects/{id}/file: Create or overwrite file (folder_id, filename, content, is_base64).

• PATCH /api/projects/{id}/file: Patch file (path_or_doc_id, old_str, new_str, replace_all).

• POST /api/projects/{id}/compile: Trigger compilation (compiler, draft, root_doc_id).

• GET /api/projects/{id}/pdf: Download the latest compiled PDF binary.

• GET /api/projects/{id}/log: Retrieve raw LaTeX compile .log.

• POST /api/projects/{id}/folder: Create subfolder (parent_folder_id, name).

• DELETE /api/projects/{id}/{entity_type}/{entity_id}: Delete entity (doc, file, folder).

🔒 Security Best Practices

1. Keep OVERLEAF_MCP_API_KEY Strong: Generate with openssl rand -hex 32.

2. Do Not Expose Raw Ports to the Public Internet: Expose the port only on your local network/VPN (Tailscale, WireGuard) or behind an authenticating reverse proxy with TLS (Cloudflare Tunnel, Caddy, Nginx).

3. Container Isolation: overleaf-ce-mcp only needs network access to overleaf, overleaf-mongo, and overleaf-redis. It does not need root privileges inside the container.

📄 License

Distributed under the MIT License.

Authored by Alan Magno.