📝 Overleaf Claude MCP

✨ Let Claude read, write, and push your Overleaf LaTeX projects — all from the chat, with minimum tokens.

An MCP (Model Context Protocol) server that connects Claude Code / Claude Desktop with your Overleaf projects — built for real LaTeX workflows where every token counts.

⚡ Why This MCP?

Large LaTeX files (a thesis main.tex is often 80–100 KB / ~35K tokens) make naive MCP workflows expensive: every "rewrite this section" would normally force Claude to emit the full file again.

v1.1.0 fixes that. Three optimizations give you order-of-magnitude token savings on real editing sessions:

Related MCP server: Overleaf MCP

🎯 What's New in v1.1.0

🚀 Performance Optimizations

• 🗜️ Sparse checkout — Only syncs text files (.tex, .bib, .bst, .cls, .sty, .bbl, .cfg). Images and PDFs are skipped, so clone and pull stay fast even on figure-heavy projects.

• 🔀 Read/write separation — Read operations pull the latest from Overleaf; write operations skip the pull and work locally. Push always pulls first to prevent conflicts.

• 🧠 Smart diff mode — read_file returns only the changes on subsequent reads instead of the full file. Your long chat session stops paying for the same content over and over.

• ✂️ patch_file tool — Replace specific text in a file without transferring the full content. The token cost scales with the edit size, not the file size.

🆚 vs mjyoo2/OverleafMCP

The upstream OverleafMCP is read-only. This fork adds full write support and the performance optimizations above:

🛠️ All Available Tools

📋 Prerequisites

• 🟢 Node.js ≥ 18

• 🔧 Git installed on your system

• 📘 An Overleaf account with Git integration enabled

🚀 Setup

1. Clone this repo

git clone https://github.com/Junfei-Z/overleaf-claude-mcp.git
cd overleaf-claude-mcp
npm install

2. Get your Overleaf credentials

You need two things:

🆔 Project ID

Open your project in Overleaf and look at the URL:

https://www.overleaf.com/project/64a1b2c3d4e5f6a7b8c9d0e1
                                  ^^^^^^^^^^^^^^^^^^^^^^^^
                                     This is your Project ID

🔑 Git Token

1. Go to Overleaf Account Settings

2. Scroll to the Git Integration section

3. Click Create token

4. Copy the token (it starts with olp_...)

⚠️ Keep your Git Token private. Never commit it to version control.

3. Configure your project(s)

cp projects.example.json projects.json

Edit projects.json:

{
  "projects": {
    "default": {
      "name": "My Paper",
      "projectId": "64a1b2c3d4e5f6a7b8c9d0e1",
      "gitToken": "olp_xxxxxxxxxxxxxxxxxxxx"
    }
  }
}

You can add multiple projects:

{
  "projects": {
    "default": {
      "name": "PhD Thesis",
      "projectId": "64a1b2c3d4e5f6a7b8c9d0e1",
      "gitToken": "olp_xxxxxxxxxxxxxxxxxxxx"
    },
    "paper2": {
      "name": "Conference Paper",
      "projectId": "75b2c3d4e5f6a7b8c9d0e1f2",
      "gitToken": "olp_yyyyyyyyyyyyyyyyyyyy"
    }
  }
}

4. Connect to Claude

Option A — Claude Code (CLI / IDE extension)

Create or edit .mcp.json in your project directory (or ~/.claude/.mcp.json for global access):

{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": ["/absolute/path/to/overleaf-claude-mcp/overleaf-mcp-server.js"]
    }
  }
}

Then restart Claude Code.

💡 Claude Code only loads .mcp.json from the directory where you launch it. Either cd into that directory first, or place it at ~/.claude/.mcp.json for global access:

cd /path/to/your/project   # where .mcp.json lives
claude                     # start Claude Code here

Option B — Claude Desktop

Edit your Claude Desktop config file:

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

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

{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": ["/absolute/path/to/overleaf-claude-mcp/overleaf-mcp-server.js"]
    }
  }
}

Then restart Claude Desktop.

💬 Usage Examples

📖 Reading

"List all files in my Overleaf project"

"Read main.tex from my Overleaf project"

"Show me all the sections in my paper"

"Get the content of the Introduction section"

✏️ Writing

"Add a new paragraph to the Related Work section"

"Fix the typo in line 42 of main.tex"

"Rewrite the abstract to be more concise"

"Push the changes to Overleaf with commit message 'Update abstract'"

✂️ Token-efficient editing (v1.1.0 sweet spot)

"Patch main.tex: replace 'old title' with 'new title'"

patch_file only transfers the specific text being changed, not the entire file. For a one-paragraph edit on a 35K-token thesis, that's the difference between ~35K tokens and ~200 tokens.

🔁 Typical Workflow

You:    "Read main.tex from my Overleaf project"
Claude: [reads via MCP — first read returns full content]

You:    "Rewrite the introduction to emphasize our main contribution"
Claude: [uses patch_file to replace just the introduction text]

You:    "Read main.tex again"
Claude: [smart mode: returns only the diff since last read]

You:    "Push to Overleaf"
Claude: [pulls latest, commits, and pushes — changes appear in Overleaf]

🧭 Pairing with Direct git (Optional, for Power Users)

For very large files or team projects, you can pair this MCP with a direct git clone of the same Overleaf project. Both use the same Git bridge, so they stay consistent.

When to use each tool:

This way MCP handles the fast-path (discover + targeted edits), and direct git handles the heavy lifting, with no duplicated state.

📋 Drop-in CLAUDE.md Template

Claude Code automatically loads CLAUDE.md from your project root. Paste the template below to lock in the hybrid workflow. Replace the two placeholders with your own values (never commit the filled-in file — add CLAUDE.md to .gitignore if your token lives inside it).

# Overleaf Workflow: MCP + Git Hybrid

This project's Overleaf (project id `<YOUR_PROJECT_ID>`) is synced via Git Bridge.
Use **MCP** for discovery and small edits; use **local git** for large-file edits.

Local clone: `/tmp/<project-name>-git` (clone once with the URL below).

Clone URL (do not commit this file if the token is filled in):
https://git:<YOUR_GIT_TOKEN>@git.overleaf.com/<YOUR_PROJECT_ID>

## Use MCP for (lightweight, cheap)
- `list_projects`, `list_files`, `get_sections`, `status_summary`
- `read_file` on short files
- `patch_file` for one-paragraph edits
- `write_file` only when the target file is < 5 KB

## Use local git for (large files, token-efficient)
- Edits to `main.tex` or any `.tex` > 5 KB
- Workflow:

cd /tmp/-git && git pull --rebase

Edit the file locally with the Edit tool

git add -A && git commit -m "" && git push

## Standard per-edit flow
1. `git pull --rebase` first (to merge any web edits)
2. Locate the change with Grep / get_sections — do NOT Read the whole file
3. Edit with str_replace (patch_file for MCP, Edit for git)
4. Commit with a specific message, then push

## Don't
- ❌ Use `write_file` to rewrite `main.tex`
- ❌ Read the whole `main.tex` (> 20 KB) into context
- ❌ `git push --force` on conflict — stop and ask instead
- ❌ Reflow unrelated paragraphs for cosmetic reasons

## Token self-check
If a single operation will read or write > 10 KB, announce the range first and
wait for confirmation.

🔐 Security reminder: the template contains placeholders <YOUR_PROJECT_ID> and <YOUR_GIT_TOKEN>. Put your real values locally, then do not commit CLAUDE.md if it contains the token. Add CLAUDE.md to .gitignore, or keep the token only in projects.json and reference it from CLAUDE.md by name.

🔧 How Sparse Checkout Works

To minimize sync time and bandwidth, the MCP server uses git sparse checkout to only download text files from your Overleaf project:

• ✅ Synced: .tex, .bib, .bst, .cls, .sty, .bbl, .cfg

• ❌ Skipped: .png, .jpg, .pdf, .eps, and all other binaries

This means:

• 🏎️ Clone and pull are much faster, especially for projects with many figures

• 🖼️ You can still reference images in your LaTeX code (they exist on Overleaf) — they just aren't downloaded locally

• 🎨 To add or modify images, use the Overleaf web editor directly

🤝 Multi-Project Usage

When using multiple projects, specify which one:

"Read main.tex from project paper2"

"List files in my PhD Thesis project"

The projectName parameter matches the key in your projects.json (e.g. "default", "paper2").

🔐 Security

• 🚫 projects.json is in .gitignore and will never be committed

• 🔒 Git tokens are only used locally to talk to Overleaf's Git bridge

• 🔄 You can rotate your token anytime in Overleaf Account Settings

❓ Troubleshooting

🌟 Credits

• Original read-only MCP server: mjyoo2/OverleafMCP

• Write/push functionality and performance optimizations by Junfei-Z with Claude Code

📄 License

MIT — see LICENSE.