# Overleaf Git MCP

> A model-agnostic MCP server for token-efficient reading, editing, and synchronization of Overleaf LaTeX projects through Git.

<p align="center">
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=node.js&logoColor=white" alt="Node.js >= 18"></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-Compatible-0A84FF" alt="MCP compatible"></a>
  <a href="https://developers.openai.com/codex/mcp"><img src="https://img.shields.io/badge/Codex-CLI%20%7C%20IDE-111111?logo=openai&logoColor=white" alt="Codex CLI and IDE"></a>
  <a href="https://claude.ai/"><img src="https://img.shields.io/badge/Claude-Code%20%7C%20Desktop-D97706?logo=anthropic&logoColor=white" alt="Claude Code and Desktop"></a>
  <a href="https://www.overleaf.com/"><img src="https://img.shields.io/badge/Overleaf-Git%20Bridge-47A141?logo=overleaf&logoColor=white" alt="Overleaf Git Bridge"></a>
  <a href="https://github.com/Junfei-Z/overleaf-git-mcp/releases"><img src="https://img.shields.io/badge/version-1.1.0-blueviolet" alt="Version 1.1.0"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
  <a href="https://github.com/Junfei-Z/overleaf-git-mcp/stargazers"><img src="https://img.shields.io/github/stars/Junfei-Z/overleaf-git-mcp?style=social" alt="GitHub stars"></a>
</p>

**Overleaf Git MCP** connects Codex, Claude Code, Claude Desktop, and other MCP clients that support local STDIO servers to your Overleaf projects.

It is built for real research-writing workflows, where LaTeX projects are large, most edits touch only a small part of a file, and repeatedly transferring entire files wastes context and tokens. The server provides targeted patching, sparse checkout, diff-based re-reading, section-aware access, and explicit Git push operations.

## Key capabilities

- Read project files and inspect LaTeX section structure.
- Apply targeted edits without rewriting complete files.
- Commit and push changes back to Overleaf through its Git bridge.
- Skip figures and other binary assets during synchronization.
- Return only changed content on repeated reads when smart diff mode is enabled.
- Manage multiple Overleaf projects from one local MCP server.
- Keep write operations local until an explicit `push_changes` call.

---

## Why use this MCP server?

A thesis or long paper can easily have an `80–100 KB` `main.tex` file — roughly `35K` tokens. A naive agent workflow re-reads or rewrites that entire file even when only one sentence changes.

The examples below show the kind of efficiency gains this design targets:

| Scenario | Naive workflow | Overleaf Git MCP | Expected effect |
|:--|:--:|:--:|:--:|
| Read a 35K-token file twice | 70K tokens | First read + subsequent diff | About 50% less repeated content |
| Replace a 50-word sentence | Rewrite the full file | About 100–200 tokens with `patch_file` | More than 99% less generated text |
| Clone a figure-heavy project | Download all assets | Download supported text files only | Lower bandwidth and faster setup |
| Revisit the same file in one session | Return the full file each time | Return only detected changes | Stable context usage |

Actual savings depend on the project structure, client behavior, and the edit being requested.

---

## What is new in v1.1.0?

### Sparse checkout

Only supported text files are synchronized:

- `.tex`
- `.bib`
- `.bst`
- `.cls`
- `.sty`
- `.bbl`
- `.cfg`

Images, PDFs, and other binary assets are skipped. This keeps clone and pull operations lightweight for projects with many figures.

### Read/write separation

- Read operations pull the latest state from Overleaf.
- Write operations modify the local working copy without automatically pulling.
- `push_changes` pulls before committing and pushing, reducing the risk of overwriting remote work.

### Smart diff mode

After the first `read_file` call, subsequent reads can return only detected changes instead of the full file. Use `mode="full"` when complete content is required.

### Targeted patching

`patch_file` replaces specific text without transferring or regenerating an entire file, so its cost scales with the size of the edit rather than the size of the document.

---

## Comparison with the upstream project

This project began as a fork of [`mjyoo2/OverleafMCP`](https://github.com/mjyoo2/OverleafMCP). The upstream project provides read-oriented Overleaf access; Overleaf Git MCP adds write, push, and token-efficiency features.

| Capability | `mjyoo2/OverleafMCP` | Overleaf Git MCP |
|:--|:--:|:--:|
| Read files from Overleaf | Yes | Yes |
| Parse LaTeX sections | Yes | Yes |
| List projects and files | Yes | Yes |
| Show a project status summary | Yes | Yes |
| Write or edit files | No | Yes |
| Commit and push to Overleaf | No | Yes |
| Patch specific text | No | Yes |
| Sparse checkout | No | Yes |
| Smart diff on repeated reads | No | Yes |

---

## Available MCP tools

| Tool | Description |
|:--|:--|
| `list_projects` | List all configured Overleaf projects. |
| `list_files` | List synchronized text files in a project. Images and PDFs are omitted by design. |
| `read_file` | Read a file. Smart mode can return only changes on later reads; pass `mode="full"` for complete content. |
| `get_sections` | Extract section and subsection headings without reading the entire document body. |
| `get_section_content` | Return the body of a named section. |
| `write_file` | Write a complete local file. It does not automatically pull first. |
| `patch_file` | Replace targeted text without transferring the full file. |
| `push_changes` | Pull, commit, and push local changes to Overleaf. |
| `status_summary` | Show project status and local changes, including `git diff --stat`. |

---

## Requirements

- Node.js 18 or later
- Git
- An Overleaf account with Git integration enabled
- A local MCP client that supports STDIO servers

---

## Installation

### 1. Clone the repository

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

### 2. Obtain your Overleaf credentials

You need an Overleaf project ID and Git token.

#### Project ID

Open the project in Overleaf and inspect its URL:

```text
https://www.overleaf.com/project/64a1b2c3d4e5f6a7b8c9d0e1
                                  ^^^^^^^^^^^^^^^^^^^^^^^^
                                  project ID
```

#### Git token

1. Open [Overleaf Account Settings](https://www.overleaf.com/user/settings).
2. Find **Git Integration**.
3. Select **Create token**.
4. Copy the token beginning with `olp_`.

> [!CAUTION]
> Treat the Git token as a password. Do not commit it, paste it into issues, or include it in screenshots and logs.

### 3. Configure one or more projects

Create a local configuration file:

```bash
cp projects.example.json projects.json
```

Edit `projects.json`:

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

Multiple projects are supported:

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

`projects.json` is excluded through `.gitignore` and should remain local.

---

## Connect an MCP client

The server is launched as a local STDIO process with:

```text
Command: node
Arguments: /absolute/path/to/overleaf-git-mcp/overleaf-mcp-server.js
```

Use an absolute path in client configuration.

### Option A: Codex CLI or IDE extension

Add the server from the terminal:

```bash
codex mcp add overleaf -- node /absolute/path/to/overleaf-git-mcp/overleaf-mcp-server.js
```

Verify the configuration:

```bash
codex mcp list
```

The Codex CLI and IDE extension share MCP configuration. Restart the IDE extension if it was already running when the server was added.

You can also configure the server manually in `~/.codex/config.toml` or a project-level `.codex/config.toml`:

```toml
[mcp_servers.overleaf]
command = "node"
args = ["/absolute/path/to/overleaf-git-mcp/overleaf-mcp-server.js"]
```

In an active Codex session, use `/mcp` to inspect available MCP servers and tools.

### Option B: Claude Code

Create or edit `.mcp.json` in the directory from which Claude Code is launched:

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

Restart Claude Code after changing the configuration.

### Option C: Claude Desktop

Edit the Claude Desktop configuration file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

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

Restart Claude Desktop after saving the file.

### Option D: Other MCP clients

Configure a local STDIO server using `node` as the command and the absolute path to `overleaf-mcp-server.js` as its argument. Registration steps differ by client.

---

## Usage examples

### Read and inspect

```text
List all configured Overleaf projects.
```

```text
List the files in my default Overleaf project.
```

```text
Read main.tex in full.
```

```text
Show the section structure of main.tex.
```

```text
Return only the content of the Introduction section.
```

### Edit

```text
Replace "old title" with "new title" in main.tex using patch_file.
```

```text
Add one paragraph to the Related Work section without rewriting unrelated content.
```

```text
Create a new references fragment in sections/references.tex.
```

### Review and push

```text
Show the local diff summary before pushing.
```

```text
Push the changes to Overleaf with commit message "Revise introduction".
```

---

## Recommended workflow

```text
User:  Read main.tex from the default Overleaf project.
Agent: Retrieves the latest file through read_file.

User:  Rewrite one paragraph in the introduction.
Agent: Uses patch_file to change only the requested passage.

User:  Show what changed.
Agent: Uses read_file smart mode or status_summary to return the diff.

User:  Push the approved changes to Overleaf.
Agent: Pulls the latest remote state, commits, and pushes through push_changes.
```

The safety boundary is deliberate: inspect and edit locally first, review the diff, and push only once the changes are approved.

---

## MCP and direct Git hybrid workflow

For very large rewrites or complex merge resolution, a direct Git clone works well alongside the MCP server — both talk to the same Overleaf Git bridge.

| Task | Recommended method |
|:--|:--|
| Discover projects and files | MCP: `list_projects`, `list_files` |
| Inspect document structure | MCP: `get_sections`, `get_section_content` |
| Small targeted edits | MCP: `patch_file` |
| Create short text files | MCP: `write_file` |
| Rewrite several large sections | Direct Git and a local editor |
| Resolve non-trivial conflicts | Direct Git |
| Review pending changes | MCP: `status_summary` or direct `git diff` |
| Commit and push approved edits | MCP: `push_changes` or direct Git |

### Agent instructions template

Codex users can save the following as `AGENTS.md`. Claude Code users can place the same workflow rules in `CLAUDE.md`.

```markdown
# Overleaf Editing Workflow

This project is synchronized with Overleaf through its Git bridge.
Use Overleaf Git MCP for discovery and targeted edits. Use direct Git for large
rewrites or manual conflict resolution.

## Use MCP for

- Listing projects and files
- Inspecting LaTeX sections
- Reading short files or specific sections
- Applying small, exact replacements with patch_file
- Reviewing status before a push

## Use direct Git for

- Multi-section rewrites
- Files that are too large to load safely into context
- Complex merges or conflicts
- Operations involving figures or binary assets

## Editing rules

1. Synchronize before editing.
2. Locate the smallest relevant section or text range.
3. Change only content required by the task.
4. Review the diff before committing.
5. Use a specific commit message.
6. Never force-push to resolve a conflict.
7. Never expose an Overleaf Git token in prompts, logs, or committed files.

## Token and scope checks

- Prefer get_sections or get_section_content over reading a full long document.
- Prefer patch_file over write_file for small edits.
- Do not reformat unrelated paragraphs.
- Ask before reading or replacing an unexpectedly large text range.
```

> [!IMPORTANT]
> Do not store an Overleaf token in `AGENTS.md`, `CLAUDE.md`, `.mcp.json`, or any committed file. Keep credentials only in the ignored local `projects.json` file or an appropriate credential manager.

---

## Sparse checkout behavior

The server intentionally synchronizes supported LaTeX-related text files and skips binary assets.

### Synchronized

- `.tex`
- `.bib`
- `.bst`
- `.cls`
- `.sty`
- `.bbl`
- `.cfg`

### Not synchronized

- `.png`
- `.jpg` and `.jpeg`
- `.pdf`
- `.eps`
- Other unsupported or binary files

You can continue referencing existing figures from LaTeX because they remain in the Overleaf project. Add or modify binary assets through the Overleaf web editor or a full direct Git clone.

---

## Multi-project usage

Specify the project key defined in `projects.json`:

```text
Read main.tex from project paper2.
```

```text
List files in my PhD Thesis project.
```

The `projectName` parameter corresponds to keys such as `default` and `paper2`, not necessarily the human-readable `name` field.

---

## Security model

- The MCP server runs locally as a STDIO process; this repository does not provide a hosted proxy service.
- Overleaf project IDs and Git tokens remain in the local `projects.json` file.
- `projects.json` is excluded through `.gitignore`.
- The Git token is used to authenticate with Overleaf's Git bridge.
- Local edits are not sent to Overleaf until `push_changes` or a direct `git push` is executed.
- `push_changes` pulls before pushing to reduce accidental overwrites.
- Force-push behavior is not part of the recommended workflow.
- If a token is exposed, revoke it immediately in Overleaf Account Settings and create a replacement.

The MCP client and model may receive document content when tools return it. Review the privacy and data-handling settings of the client you use.

---

## Current limitations

- Only the configured text-file extensions are synchronized through sparse checkout.
- Binary assets cannot be uploaded or edited through the current MCP tools.
- Git integration must already be enabled for the Overleaf account and project.
- Complex merge conflicts may require manual resolution in a direct Git clone.
- `write_file` does not automatically pull first; use a fresh read or pull-aware workflow before replacing a complete file.

---

## Troubleshooting

| Problem | Resolution |
|:--|:--|
| MCP server does not appear | Confirm the absolute script path, then restart the client or IDE extension. |
| `Error loading projects.json` | Run `cp projects.example.json projects.json` and complete the required fields. |
| Git clone fails | Verify the project ID, Git token, account access, and Overleaf Git integration. |
| Push fails | Check token write access and whether remote changes introduced a conflict. |
| A figure or PDF is missing locally | Sparse checkout intentionally skips binary assets. |
| Repeated reads still consume too much context | Use `get_sections`, `get_section_content`, `patch_file`, and smart diff mode. |
| Codex cannot see the server | Run `codex mcp list`, check the command and path, and inspect `/mcp` in the active session. |
| A token appeared in a log or issue | Remove the content, revoke the token, and generate a replacement immediately. |

When reporting a bug, include the operating system, Node.js version, MCP client, reproduction steps, and redacted logs. Never include a live Git token.

---

## Repository rename

This project was previously named `overleaf-claude-mcp`. The new name reflects that the server works with any MCP client, not just one model provider.

Update an existing local clone with:

```bash
git remote set-url origin https://github.com/Junfei-Z/overleaf-git-mcp.git
git remote -v
```

Also update paths in `.mcp.json`, `claude_desktop_config.json`, `.codex/config.toml`, scripts, badges, and documentation.

---

## Contributing

Focused issues and pull requests are welcome, particularly for:

- MCP client compatibility
- Git conflict handling
- Tests and continuous integration
- Security hardening
- Additional safe LaTeX editing tools
- Documentation and reproducible examples

Before opening an issue, remove credentials and minimize any private LaTeX content included in logs or examples.

---

## Credits

- Original read-oriented MCP server: [`mjyoo2/OverleafMCP`](https://github.com/mjyoo2/OverleafMCP)
- Write/push functionality and performance optimizations: [Junfei-Z](https://github.com/Junfei-Z)

---

## License

MIT License. See [LICENSE](LICENSE).