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

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

Open Overleaf Account Settings.
Find Git Integration.
Select Create token.
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:

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

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

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

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:

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.

Name		Name	Last commit message	Last commit date
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
overleaf-mcp-server.js		overleaf-mcp-server.js
package-lock.json		package-lock.json
package.json		package.json
projects.example.json		projects.example.json

Latest commit

History

Folders and files

Repository files navigation