Overleaf Git MCP

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

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

It is designed for real research-writing workflows in which LaTeX projects are large, edits are usually local, and repeatedly transferring an entire file 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.

Related MCP server: Overleaf MCP

Why use this MCP server?

A thesis or long paper can contain an 80–100 KB main.tex file, which may correspond to roughly 35K tokens. A naive agent workflow may repeatedly read or rewrite that entire file even when only one sentence changes.

The examples below illustrate the intended efficiency gains:

These figures are illustrative and depend on the project structure, client behavior, and requested edit.

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. 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. The upstream project provides read-oriented Overleaf access; Overleaf Git MCP adds write, push, and token-efficiency features.

Available MCP tools

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

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:

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

Git token

1. Open Overleaf Account Settings.

2. Find Git Integration.

3. Select Create token.

4. Copy the token beginning with olp_.

3. Configure one or more projects

Create a local configuration file:

cp projects.example.json projects.json

Edit projects.json:

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

Multiple projects are supported:

{
  "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:

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:

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

Verify the configuration:

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:

[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:

{
  "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

{
  "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

List all configured Overleaf projects.

List the files in my default Overleaf project.

Read main.tex in full.

Show the section structure of main.tex.

Return only the content of the Introduction section.

Edit

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

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

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

Review and push

Show the local diff summary before pushing.

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

Recommended workflow

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 recommended safety boundary is explicit: inspect and edit locally first, review the diff, and push only after approval.

MCP and direct Git hybrid workflow

For very large rewrites or complex merge resolution, use a direct Git clone alongside the MCP server. Both workflows communicate with the same Overleaf Git bridge.

Agent instructions template

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

# 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.

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:

Read main.tex from project paper2.

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

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 is compatible with multiple MCP clients rather than one model provider.

Update an existing local clone with:

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

• Write/push functionality and performance optimizations: Junfei-Z

License

MIT License. See LICENSE.