🍃 Overleaf MCP Helper

Let AI assistants read, edit, and manage your Overleaf LaTeX projects — safely.

Overleaf MCP Helper is a Model Context Protocol (MCP) server paired with a VSCode extension that bridges AI assistants (Claude, ChatGPT, Copilot, etc.) to your Overleaf projects. Write, refactor, and manage LaTeX papers with AI — without ever leaving Overleaf.

✨ Features

• 📖 Read any file in your Overleaf project
• ✏️ Edit files with safe, exact-match substring replacement (no full-file overwrites!)
• 📄 Create new files (with overwrite protection)
• 🗑️ Delete files (directory deletion blocked for safety)
• 📁 Rename / Move files within the project
• 🔍 Search across all project files with regex
• 📊 Parse LaTeX logs — extract errors, warnings, and bad boxes from compile output
• 🌳 Tree view of the project structure
• 🔄 Auto-retry with connection recovery on network failures

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                   AI Assistant                          │
│            (Claude / ChatGPT / Copilot)                 │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP (stdio)
                       ▼
┌─────────────────────────────────────────────────────────┐
│              MCP Server (Node.js)                       │
│                                                         │
│  Tools: edit_file · create_file · delete_file           │
│         rename_file · read_file · search_in_project     │
│         get_compile_log · tree · list_files             │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP (localhost:23119)
                       ▼
┌─────────────────────────────────────────────────────────┐
│          VSCode Extension (HTTP Bridge)                  │
│                                                         │
│  Exposes vscode.workspace.fs via REST API               │
│  Endpoints: /ws/read · /ws/write · /ws/delete           │
│             /ws/rename · /ws/ls · /ws/stat · /ws/tree   │
└──────────────────────┬──────────────────────────────────┘
                       │ VSCode VFS API
                       ▼
┌─────────────────────────────────────────────────────────┐
│                    Overleaf                              │
│          (overleaf-workshop:// protocol)                 │
└─────────────────────────────────────────────────────────┘

📦 Installation

Prerequisites

• VSCode
• Overleaf Workshop extension (to open Overleaf projects in VSCode)
• Node.js ≥ 18

Step 1: Install the VSCode Extension

Option A: Use the pre-built .vsix (recommended)

A pre-built extension is available in the dist/ directory:

1. Download dist/overleaf-mcp-helper-extension-1.0.0.vsix
2. In VSCode: Extensions → ··· → Install from VSIX... → select the downloaded file

Option B: Build from source

cd extension
npm install
npm run compile
npm run package

This will generate a .vsix file in the extension/ directory (e.g. extension/overleaf-mcp-helper-extension-1.0.0.vsix).

Install it in VSCode: Extensions → ··· → Install from VSIX... → select the generated .vsix file.

Step 2: Configure the MCP Server

First, install MCP server dependencies:

cd mcp-server
npm install

Then add to your MCP configuration file (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": ["/path/to/overleaf-mcp-helper/mcp-server/index.mjs"]
    }
  }
}

Step 3: Open an Overleaf Project

1. Open an Overleaf project in VSCode via the Overleaf Workshop extension
2. The bridge extension auto-starts an HTTP server on localhost:23119
3. The MCP server auto-discovers the bridge and connects

That's it! Your AI assistant can now interact with your Overleaf project. 🎉

🛠️ Available Tools

File Operations

| Tool | Description | Safety | |------|-------------|--------| | read_file | Read a single file by path | ✅ Read-only | | read_multiple_files | Read multiple files at once | ✅ Read-only | | edit_file | Replace an exact substring (must match uniquely) | ✅ Safe — rejects ambiguous matches | | create_file | Create a new file (rejects if exists) | ✅ Safe — no overwrite | | delete_file | Delete a file (rejects directories) | ⚠️ Destructive — files only | | rename_file | Rename or move a file (rejects if dest exists) | ⚠️ Destructive — no overwrite |

Search & Navigation

| Tool | Description | |------|-------------| | list_projects | List all open workspaces/projects | | list_files | Recursively list all files | | tree | Visual directory tree (configurable depth) | | search_in_project | Regex search across text files |

LaTeX-Specific

| Tool | Description | |------|-------------| | get_compile_log | Parse .log file — extract errors, warnings, bad boxes |

⚙️ Configuration

Environment Variables (MCP Server)

| Variable | Default | Description | |----------|---------|-------------| | VFS_BRIDGE_PORT | 23119 | Base port for bridge discovery | | VFS_BRIDGE_TIMEOUT | 10000 | HTTP request timeout (ms) | | VFS_BRIDGE_WRITE_TIMEOUT | 15000 | Write request timeout (ms) | | VFS_BRIDGE_RETRIES | 2 | Max retries on connection failure |

Extension Settings (VSCode)

| Setting | Default | Description | |---------|---------|-------------| | overleafMcpHelper.port | 23119 | HTTP server port | | overleafMcpHelper.autoStart | true | Auto-start when VFS workspace detected |

🔒 Safety Design

This project prioritizes safety to protect your precious LaTeX manuscripts:

1. No full-file overwrite — We deliberately removed the write_file tool. All edits go through edit_file which requires an exact, unique match.
2. Overwrite protection — create_file rejects if the file exists. rename_file rejects if the destination exists.
3. Directory protection — delete_file only works on files, not directories.
4. Automatic retry — Network failures trigger port re-discovery and retry, not data corruption.
5. Overleaf version history — Even if something goes wrong, Overleaf keeps full version history for recovery.

📄 License

MIT — use it however you like.

Made with ❤️ for the academic community.

If this tool helps you write papers faster, consider giving it a ⭐!