Content
# Overleaf MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that connects your Overleaf LaTeX projects to AI agents via Git. Read, write, sync, and compile Overleaf projects directly from Claude, Cursor, QoderWork, or any MCP-compatible client.
## Features
- **Project Management** — Register, list, and remove Overleaf projects
- **File Operations** — Read, write, and list files within projects
- **Git Sync** — Pull latest changes and push edits back to Overleaf
- **LaTeX Compilation** — Compile locally and parse error/warning logs (requires a local LaTeX engine)
All file modifications are auto-committed locally. You control when to push changes to Overleaf, giving you a safe review-before-push workflow.
## Tools
| Tool | Description |
|------|-------------|
| `list_projects` | List all registered Overleaf projects |
| `add_project` | Register and clone a project from Overleaf via Git |
| `remove_project` | Remove a project from the registry (local files preserved) |
| `pull_project` | Pull latest changes from Overleaf (`git pull --rebase`) |
| `list_files` | List files in a project directory |
| `read_file` | Read a file from a project |
| `write_file` | Write content to a file (auto-commits locally, does not push) |
| `push_changes` | Push local commits to Overleaf |
| `compile_project` | Compile LaTeX locally and return errors/warnings |
## Prerequisites
- **Node.js** >= 18
- **Git** installed and available in PATH
- **Overleaf Git access** enabled for your project:
1. Open your project on Overleaf
2. Click **Menu** (top-left)
3. Toggle **Git** to **On**
- **LaTeX engine** (optional, for `compile_project`): one of `latexmk`, `pdflatex`, `tectonic`, or `xelatex`
### First-Time Git Authentication
Overleaf requires authentication for Git operations. Before using `add_project`, run the clone command once in your terminal to store credentials:
```bash
git clone https://git.overleaf.com/<your-project-id>
```
Enter your Overleaf email and password (or [access token](https://www.overleaf.com/user/settings#git-integration)) when prompted. After this, the MCP server can clone and sync without re-entering credentials.
> **Note:** If you sign in to Overleaf via Google or another third-party provider, you need to set a password first at [Overleaf Account Settings](https://www.overleaf.com/user/settings).
## Installation
### 1. Clone and install
```bash
git clone https://github.com/fh120/overleaf-mcp.git
cd overleaf-mcp
npm install
```
### 2. Configure your MCP client
Add the server to your MCP client's configuration. Replace the path with your actual installation path.
#### Claude Desktop
Edit `claude_desktop_config.json`:
```json
{
"mcpServers": {
"overleaf": {
"command": "node",
"args": ["/path/to/overleaf-mcp/index.mjs"]
}
}
}
```
#### Cursor
Go to **Settings → MCP → Add MCP Server**, select type `command`, and enter:
- **Command:** `node`
- **Args:** `/path/to/overleaf-mcp/index.mjs`
#### QoderWork
Go to **Settings → Connectors → Custom MCP → Add**, paste:
```json
{
"mcpServers": {
"overleaf": {
"command": "node",
"args": ["/path/to/overleaf-mcp/index.mjs"]
}
}
}
```
#### Windsurf / Cline / Continue
Follow the respective MCP server configuration docs. The format is the same:
```json
{
"command": "node",
"args": ["/path/to/overleaf-mcp/index.mjs"]
}
```
## Usage Examples
### Register a project
Ask your AI agent:
> "Add my Overleaf project with ID `6a1cf19e521e2b6b65506658` and call it `my-paper`"
This clones the project to `workspace/my-paper/` inside the server directory.
### Read and edit files
> "Read `main.tex` from `my-paper`"
> "In `my-paper`, update the abstract in `main.tex` to: ..."
Changes are auto-committed locally. To sync to Overleaf:
> "Push changes to my-paper"
### Sync from Overleaf
> "Pull the latest version of `my-paper` from Overleaf"
### Compile locally
> "Compile `my-paper` and show me any errors"
Requires a local LaTeX engine. If none is found, the tool returns installation instructions.
## Project Structure
```
overleaf-mcp/
├── index.mjs # MCP server (all tools in a single file)
├── package.json
├── config.json # Auto-generated project registry (gitignored)
├── workspace/ # Cloned projects live here (gitignored)
└── .gitignore
```
## How It Works
```
┌─────────────┐ MCP (stdio) ┌──────────────────┐ git clone/push/pull ┌──────────┐
│ AI Agent │◄───────────────────►│ Overleaf MCP │◄──────────────────────────►│ Overleaf │
│ (Claude, │ │ Server │ │ Git │
│ Cursor..) │ │ (Node.js) │ │ Server │
└─────────────┘ └──────────────────┘ └──────────┘
```
1. The AI agent sends tool calls via MCP stdio transport
2. The server translates calls into Git operations on local project clones
3. Changes sync to/from Overleaf via `git push` and `git pull`
## Troubleshooting
### Git clone fails with authentication error
Run `git clone https://git.overleaf.com/<project-id>` in your terminal first to store credentials. If you use Google/third-party login, set a password at [Overleaf Settings](https://www.overleaf.com/user/settings).
### Git Credential Manager (GCM) hangs
On Windows, GCM may cause timeouts in non-interactive terminals. Set these environment variables before starting the server:
```bash
export GCM_INTERACTIVE=never
export GCM_AUTODETECT_TIMEOUT=1
export GIT_TERMINAL_PROMPT=0
```
### `compile_project` says no LaTeX engine found
Install one of:
- [MiKTeX](https://miktex.org/download) (Windows, recommended)
- [TeX Live](https://tug.org/texlive/) (cross-platform)
- [Tectonic](https://tectonic-typesetting.github.io/) (lightweight)
Or push changes to Overleaf and compile via the web interface.
## License
MIT
