mcp-server-overleaf

# mcp-server-overleaf

Your papers live on Overleaf, and the model you want to write with cannot reach them.
Copy-pasting sections into a chat window works until you paste something back and quietly
flatten a change your co-author made ten minutes ago. This is an MCP server that gives an
AI client real access to your Overleaf projects over the official git bridge: it reads the
actual files, edits them in a local clone, and publishes only when you say so. Before every
read and before every push it checks what your collaborators have done, and if your edit
and theirs touch the same lines it refuses to push and shows you both versions rather than
picking a winner. Losing someone else's work is the one outcome it is built to prevent.

---

Independent community project; not affiliated with or endorsed by Overleaf.

## Why this one

Several Overleaf MCP servers exist. Of the ones built on Overleaf's official Git bridge,
this is the most complete, and it is the only one that stops instead of overwriting when a
co-author has already changed the lines you are editing.

- **A conflict ends the push, not your co-author's paragraph.** Every read and every push
  first checks what changed on Overleaf. When two edits touch the same lines, `push_changes`
  refuses and shows you both versions.
- **16 tools, and nothing reaches Overleaf until you say so.** Read, search, and edit by
  section or by exact text, compile locally, inspect the diff, then publish deliberately.
- **No terminal, if you do not want one.** Claude Desktop installs it from a downloaded
  bundle; Claude Code and Codex install it as a plugin.
- **The token is written once, to one file, at mode 600.** No client configuration holds
  it, and the published plugin declares no environment variables at all.

[Related projects](docs/related-projects.md) compares the alternatives tool by tool, and is
equally direct about the things this server cannot do.

## Where it installs

Every route below reaches the same server and the same 16 tools, and every one of them
keeps edits local until an explicit push. Pick the row for your client.

| Client | How to install it |
| --- | --- |
| Claude Desktop | Download the bundle and double-click it. [One click](#install-into-claude-desktop-with-one-click) |
| Claude Code | Add this repository as a plugin marketplace. [Two commands](#install-as-a-claude-code-or-codex-plugin) |
| Codex CLI, desktop, and IDE extension | The same, with the Codex commands. [Two commands](#install-as-a-claude-code-or-codex-plugin) |
| Cursor | `npx --yes mcp-server-overleaf setup`. [One command](#install-with-one-command) |
| Visual Studio Code | A `.vscode/mcp.json` entry. [Guide](docs/connect-local-mcp-clients.md#6-visual-studio-code) |
| ChatGPT on the web and desktop | An outbound-only Secure MCP Tunnel, no public endpoint and no open port. [Guide](docs/connect-chatgpt-with-secure-mcp-tunnel.md) |
| A catalogue that reads the MCP registry | Already listed as `io.github.yangzichao/mcp-server-overleaf`. [Details](#find-it-in-the-mcp-registry) |
| Any other MCP client | `npx --yes mcp-server-overleaf --stdio`, or Streamable HTTP. [By hand](#install-from-npm-by-hand) |
| A machine you are developing on | A source checkout. [From source](#install-from-a-source-checkout) |

Claude Desktop takes a packaged bundle; Claude Code and Codex each take a plugin.
Everywhere else `setup` does the equivalent. All four routes end the same way: the token is
verified against Overleaf, written to one file at mode 600, and no client configuration
holds the secret.

## Guides

- [Project configuration and efficient reads](docs/project-workflows.md) covers independent credentials,
  sparse checkout, revision reads, and guarded edits.
- [Related projects](docs/related-projects.md) describes existing alternatives and this
  project's focus on collaborator safety and recovery.
- [Release process and verification](docs/releasing.md) describes the tested artifact,
  provenance, first publication, and subsequent trusted publishing.
- [Install the Claude Desktop bundle](docs/install-claude-desktop-bundle.md) covers the
  one-click `.mcpb` extension: what is inside it, how to build it, and how to remove it.
- [Install the Claude Code and Codex plugins](docs/install-plugins.md) covers the two
  marketplace entries: what the plugin contains, how it gets a token without holding one,
  and how to update, remove, or build it.
- [Connect local MCP clients to Overleaf](docs/connect-local-mcp-clients.md) covers Codex
  desktop and CLI, Claude Code, Claude Desktop, Cursor, Visual Studio Code, local stdio,
  verification, and troubleshooting.
- [Connect ChatGPT to Overleaf with Secure MCP Tunnel](docs/connect-chatgpt-with-secure-mcp-tunnel.md)
  covers the complete private connection from a local stdio server to ChatGPT desktop and
  web, including workspace association, least-privilege credentials, validation, and
  troubleshooting.

## What you are installing

An MCP server exposing 16 tools over stdio or Streamable HTTP. One core, two transports;
the tool implementations are identical and only the framing differs. `setup` connects it
to the AI clients on this computer and is the only command most people need.

Requires Node 22.14+ and git on PATH; Node 24 LTS is recommended. `compile_project` additionally needs `latexmk` and a TeX
distribution; every other tool works without them.

The release test matrix covers macOS and Linux. Windows Git and TeX workflows are not yet
validated. This server is a command-line application, not an importable JavaScript library.

Git integration has to be available for the project. Overleaf documents it as a premium
feature gated on the **project owner's** subscription, so a free account invited to a
project owned by someone with a subscription can still use it, and that subscription can be
individual, group, or institutional. Do not tell a user their own plan disqualifies them.
Verify it directly in step 3 instead.

## Install into Claude Desktop with one click

Download **[mcp-server-overleaf.mcpb](https://github.com/yangzichao/mcp-server-overleaf/releases/latest/download/mcp-server-overleaf.mcpb)**
and double-click it. Claude Desktop opens an install panel, asks for the two values below,
and starts the server itself. No terminal, no Node installation, no build.

- **Overleaf project address** — open the project in Overleaf and copy the whole URL from
  the address bar.
- **Overleaf Git token** — generate one at <https://www.overleaf.com/user/settings> under
  Git integration. Claude Desktop stores it in the operating system keychain.

The bundle carries the same server npm publishes, with its locked runtime dependencies and
nothing else. It is macOS and Windows only, because that is where Claude Desktop runs. For
any other client, use the command below. Details in
[Install the Claude Desktop bundle](docs/install-claude-desktop-bundle.md).

## Install as a Claude Code or Codex plugin

Store the token once:

```bash
npx --yes mcp-server-overleaf@0.3.2 setup --clients none
```

Then, in Claude Code:

```bash
claude plugin marketplace add yangzichao/mcp-server-overleaf
claude plugin install overleaf@mcp-server-overleaf
```

Or in Codex:

```bash
codex plugin marketplace add yangzichao/mcp-server-overleaf
codex plugin add overleaf@mcp-server-overleaf
```

Restart the client, then ask it to list the files in your project.

Neither client has a central plugin directory. In both, a marketplace is just a Git
repository, so this one is its own: Claude Code reads `.claude-plugin/marketplace.json` out
of it and Codex reads `.agents/plugins/marketplace.json`, and both point at the same
`plugins/overleaf` directory. That plugin holds no token and sets no environment variable,
because the first command writes the token to `~/.config/overleaf-mcp/projects.json` and the
server finds it there. Details in
[Install the Claude Code and Codex plugins](docs/install-plugins.md).

## Install with one command

```bash
npx --yes mcp-server-overleaf@0.3.2 setup
```

It checks Node and git, asks for the project and a token, proves the token reaches Overleaf
before writing anything, and registers the server with the clients it finds on this
computer: Claude Code, Codex, Claude Desktop and Cursor. A failed run leaves no
half-configuration behind, because nothing is written until Overleaf accepts the token.

Two things are needed, both from the browser:

- **The project address.** Open the project in Overleaf and copy the whole URL from the
  address bar. A read-only share link is a different thing, and setup says so rather than
  failing later.
- **A git authentication token**, generated at <https://www.overleaf.com/user/settings>
  under Git integration. It is not echoed as you type.

The token is written to `~/.config/overleaf-mcp/projects.json` at mode 600 and nowhere
else. The server finds that file on its own, so no client configuration holds the secret,
a path to it, or any environment variable. Clients are registered with an absolute Node
path and an absolute entry point rather than `npx`, because a desktop application starts
with a much smaller PATH than a terminal.

Restart Claude Desktop, Cursor, or Codex afterwards; Claude Code picks it up on the next
run. Then ask the assistant to list the files in the project.

Setup can also run unattended:

```bash
printf '%s' "$OVERLEAF_TOKEN" | npx --yes mcp-server-overleaf@0.3.2 setup \
  --project paper=https://www.overleaf.com/project/64a1b2c3d4e5f6a7b8c9d0e1 \
  --token-stdin --yes
```

`--clients claude-code,codex` limits which clients are touched, and `--clients none`
writes the configuration without registering anything. Run it again to add another
project or to replace an expired token; the previous file is kept alongside it.

## Find it in the MCP registry

The server is listed in the official Model Context Protocol registry as
`io.github.yangzichao/mcp-server-overleaf`. The listing names the npm package and the Claude
D