LeafMCP MCP server
Commit Oct 14, 2026Allows AI assistants to read, edit, and compile Overleaf projects directly through an MCP server.
Also known as CherryLemon/leafmcp
- Stars
- 0
- Tools
- 26
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 14, 2026
- License
- MIT
What is LeafMCP MCP?
LeafMCP allows AI assistants to read, edit, and compile Overleaf projects directly through an MCP server. It exposes 26 tools, such as list_projects, use_project, project_overview.
Summary generated from the project's README
About LeafMCP MCP server
Researchers and academics can manage LaTeX documents by connecting AI assistants directly to their Overleaf accounts. Instead of copying text back and forth between a chat window and a browser, this remote MCP server allows tools like Gemini, Claude, and ChatGPT to read, edit, and compile projects in real time. The server acts as a bridge that implements an OAuth 2.1 authorization server, ensuring that web-based AI clients can securely interact with your documents.
Users set up the server on a public HTTPS endpoint or via a local stdio connection for desktop clients like Cursor or Claude Desktop. It requires an Overleaf session cookie to authenticate and uses a local git mirror to provide version control for every change. The system includes 26 LaTeX-aware tools for tasks such as searching files, managing review comments, and performing atomic revisions through change sets. It also features a compile-and-check loop that returns distilled error summaries instead of massive log files.
What you can do with it
- 1Automated LaTeX editingAsk an AI assistant to refine a specific paragraph or fix citation errors directly within your active Overleaf project.
- 2Error debugging and compilationRequest the assistant to compile your document and provide a concise summary of any LaTeX errors or warnings.
- 3Managing peer review feedbackHave the AI assistant list, respond to, or resolve comments left by reviewers in the Overleaf interface.
- 4Safe multi-file revisionsGroup complex changes across multiple files into a single atomic update to ensure project consistency.
Written from the project's README. Every use case is checked against a quote from it.
LeafMCP MCP tools 26
Detected from the READMElist_projectsuse_projectproject_overviewlist_filesread_fileread_filessearch_projectfile_outlineedit_filewrite_filedelete_filerename_file
Show all 26 toolsShow fewer tools
pending_changescompilepublish_changespull_projectedit_historyundo_operationundo_last_editbegin_change_setcommit_change_setabandon_change_setlist_commentsadd_commentreply_to_commentresolve_comment
Configuration
CF_TUNNEL_TOKENMCP_DOMAINOLMCP_DATA_DIROVERLEAF_SESSIONPUBLIC_URL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecherrylemon/leafmcp is public and reachablegithub.com/cherrylemon/leafmcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-14github.com/cherrylemon/leafmcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model26 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubLeafMCP
A remote MCP server that lets AI assistants read and edit your Overleaf projects.
Ask Gemini, Claude, or ChatGPT to tighten a paragraph, fix a broken \cite, or update a table —
and watch it happen in your actual Overleaf project, not in a chat window you then copy from.
Table of contents
- Why this exists
- Features
- Architecture
- Quick start
- Deployment
- Connecting clients
- Tools
- Configuration
- Security model
- Troubleshooting
- Development
- Limitations
- Acknowledgements
- License
Why this exists
Overleaf has no public API for editing project files, and the AI assistants people actually pay for do not expose an API at all. Three facts shaped this project:
1. Overleaf cannot be embedded in another page. www.overleaf.com sends
X-Frame-Options: SAMEORIGIN, so a single-page app with "real Overleaf on the left, chat on the
right" is not possible. LeafMCP takes the opposite approach: Overleaf stays open in your
browser as usual, and the assistant edits the same project through the server. Reload and the
change is there.
2. A Gemini subscription is not API access. Google AI Pro / Ultra are subscriptions to the
Gemini app; they do not include quota for generativelanguage.googleapis.com, which is billed
separately through AI Studio. "Use my subscription" therefore means letting the web app call
tools, which is exactly what MCP is for — rather than holding an API key ourselves.
3. OAuth is the only thing all three clients agree on. ChatGPT documents no way to send a static API key to a custom MCP server; Gemini's custom-app flow is OAuth-only with no token fallback; Claude supports static headers but only in a limited beta. So this server ships a real OAuth 2.1 authorization server (dynamic client registration, PKCE, refresh rotation, RFC 9728 / RFC 8414 discovery). It is not optional — without it the server simply does not connect.
Features
- 26 LaTeX-aware tools — read, search, edit, rename, compile, undo, change sets, and review comments.
- Edits land in Overleaf within seconds. Each accepted change is published immediately, so your browser shows it without a manual sync.
- Atomic revisions.
begin_change_setgroups a multi-file change so it lands all at once, or not at all. - Every edit is versioned. Each change is a git commit in a local mirror;
undo_last_editreverses recent edits with a realgit revertand republishes. - Fresh reads. A file is re-fetched from Overleaf before it is read or edited, so an edit fails loudly instead of silently overwriting something you changed in the browser.
- Compile-and-check loop.
compilepublishes pending edits first, then returns a distilled error/warning summary with line numbers — not a 4,000-line LaTeX log. - Review comments are first-class: list them, act on them, reply, resolve.
- One server, several assistants. No per-client forks or special cases.
- Read-only mode, per-connection scopes, and OAuth the operator approves by hand.
Architecture
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Gemini web app │ │ Claude / │ │ Cursor / │
│ (your plan) │ │ ChatGPT │ │ Claude Desktop │
└───────┬────────┘ └───────┬────────┘ └───────┬────────┘
│ MCP over HTTPS + OAuth 2.1 │ stdio
└────────────────────┼────────────────────┘
▼
┌───────────────────────┐
│ LeafMCP server │ ← runs on your server + domain
│ · 26 LaTeX tools │
│ · OAuth 2.1 AS │
│ · git-versioned │
│ project mirrors │
└───────────┬───────────┘
│ Overleaf web session
▼
┌───────────────────────┐
│ Overleaf │
└───────────────────────┘
Requests arrive from the vendors' clouds, not from your browser, so the server must be
reachable over public HTTPS. localhost will not work for the remote clients (it works fine for
the stdio transport).
Quick start
1. Get your Overleaf session cookie
Sign in to Overleaf, open any project, then DevTools → Application → Cookies → copy the
value of overleaf_session2.
On self-hosted Overleaf / ShareLaTeX the cookie is usually
sharelatex.sid; setOVERLEAF_COOKIE_NAMEaccordingly.
This value is a full-account credential. It is held in process memory only, never written to disk, and scrubbed from every log line and tool result.
2. Configure
git clone https://github.com/CherryLemon/leafmcp.git
cd leafmcp
cp .env.example .env
Fill in at minimum OVERLEAF_SESSION, PUBLIC_URL, MCP_AUTH_MODE, and MCP_OAUTH_PASSWORD.
openssl rand -base64 24 # generate the OAuth approval passphrase
3. Build and check
npm install
npm run build
node dist/index.js --check # validate config, list every problem, start nothing
node dist/index.js --verify # exercise every Overleaf call this server makes
node dist/index.js --verify --compile # ... and include a LaTeX build
node dist/index.js # start the server
Debug in this order. Run
--verifybefore connecting anything: from inside a chat window a bad cookie, an incompatible upstream and a broken MCP setup all look the same ("something went wrong"). The verifier does not write — no upload, no comment — and reports each capability separately, so a failure names the call that broke:ok sign in and list projects — 12 project(s) ok project metadata — 4 top-level entr(ies) ok download the project archive — 812 KB ok read the archive — 37 file(s), e.g. main.tex ok download a single file (main.tex) — 9134 bytes ok list review comments — 2 thread(s)
For a first run, use a project you can afford to lose, and set OLMCP_READ_ONLY=true.
Nothing here has been exercised against a live account, so treat the first session as a test
of the bridge itself rather than a real editing session.
4. Run the tests
npm test
Deployment
Clients connect from their vendors' clouds, so the server needs a public HTTPS address.
cp .env.example .env
# PUBLIC_URL in .env must match MCP_DOMAIN exactly
MCP_DOMAIN=mcp.example.com docker compose -f docker/docker-compose.yml up -d
Caddy obtains and renews the certificate automatically. docker/Caddyfile disables response
buffering — a compile takes tens of seconds, and a buffered response looks like a hung server.
DNS requirement: the hostname needs an IPv4 A record. Claude rejects hosts that only have
AAAA records.
Without Docker
Requires Node 22+ and git on PATH:
npm ci && npm run build
PUBLIC_URL=https://mcp.example.com node dist/index.js
Put Nginx or Caddy in front for TLS.
On your own machine, with Cloudflare Tunnel
This is the right shape for a home server or a laptop-as-a-server: cloudflared dials out to
Cloudflare, so you need no public IP, no port forwarding, and no inbound firewall rule — and it
keeps working when your ISP changes your address or puts you behind CGNAT. Cloudflare terminates
TLS, so there is no Caddy in this arrangement.
CF_TUNNEL_TOKEN=<token> docker compose -f docker/docker-compose.cloudflare.yml up -d
The header of docker/docker-compose.cloudflare.yml has
the dashboard steps, including the one detail that is easy to get wrong: the tunnel's public
hostname must point at overleaf-mcp:8080 (the compose service name), not localhost:8080.
Four Cloudflare settings decide whether this works:
| Setting | Value | Why |
|---|---|---|
MCP_JSON_RESPONSES |
false |
Cloudflare returns error 524 when the origin sends nothing for 125 seconds, and a JSON-mode tool call sends nothing until it finishes — a slow LaTeX compile can trip it. SSE mode starts responding immediately and then streams. Note this is the opposite of the default, which is chosen for a same-host reverse proxy. |
| Bot Fight Mode | off | The assistants call from cloud IPs with non-browser user agents, so bot protection 403s them — and the client only reports "not a valid MCP server". |
| Cloudflare Access | do not enable | It requires an interactive login, which server-to-server clients cannot perform. LeafMCP runs its own OAuth; the consent page is opened in your browser, so Access would work for that one step and fail for everything else — a confusing half-broken state. |
| SSL/TLS mode | Full | Flexible is insecure and a common source of subtle breakage. |
Also add a cache-bypass rule for the hostname. POST /mcp is not cached by default, but a stale
.well-known/oauth-protected-resource would break OAuth discovery.
Be realistic about uptime: with this arrangement the server is available only while your machine is awake and online. A laptop that sleeps looks like a flaky assistant, and the error messages clients produce are not specific about why.
Connecting clients
The MCP endpoint is always:
https://your-domain/mcp
Gemini web app
- Open
gemini.google.comin a desktop browser. - Settings → Connected Apps → Custom apps → Add a custom app.
- Enter
https://your-domain/mcp. - LeafMCP supports dynamic client registration, so you can skip Advanced features → Show more (that is only needed for servers without DCR).
- Click Next and approve the OAuth consent screen by entering
MCP_OAUTH_PASSWORD. - Mention the app with
@appnamein a prompt.
Claude
claude.ai→ Customize → Connectors → Add → Custom → Web.- Enter
https://your-domain/mcp. - Approve the OAuth consent screen.
A free account can add one custom connector. Claude's callback
(https://claude.ai/api/mcp/auth_callback) is already allowlisted.
ChatGPT
chatgpt.com/plugins→ "+" → Add custom MCP server (older path: Settings → Connectors → Advanced → Developer mode).- Enter
https://your-domain/mcp. - Approve the OAuth consent screen.
ChatGPT's callback (https://chatgpt.com/connector_platform_oauth_redirect) is already
allowlisted.
Local clients (Cursor, Claude Desktop, MCP Inspector)
Use the stdio transport; no public address needed:
{
"mcpServers": {
"overleaf": {
"command": "node",
"args": ["/absolute/path/to/leafmcp/dist/index.js", "--stdio"],
"env": {
"OVERLEAF_SESSION": "your cookie value",
"OLMCP_DATA_DIR": "/absolute/path/to/leafmcp/data"
}
}
}
}
Verifying the connection
curl https://your-domain/healthz
curl https://your-domain/.well-known/oauth-protected-resource
Tools
26 tools. Read tools carry readOnlyHint, mutating ones carry destructiveHint, and clients use
those hints to decide when to ask for confirmation.
Projects
| Tool | Description |
|---|---|
list_projects |
List every project in the account. |
use_project |
Select the working project by id, exact name, or a unique substring. |
project_overview |
File tree, plus the section structure of the main document and any unpublished changes. |
Files
| Tool | Description |
|---|---|
list_files |
List project files with sizes. |
read_file |
Read a file with line numbers; supports start_line / end_line. |
read_files |
Read several files in one call. |
search_project |
Search all text files by substring or regular expression. |
file_outline |
Sections, labels, citations, includes and environments of one .tex file. |
edit_file |
Preferred. Replace an exact snippet; ambiguous matches are refused, and expected_hash refuses the edit if the file moved on since it was read. |
write_file |
Write a whole file, creating it if needed. |
delete_file |
Delete a file (requires explicit confirm=true). |
rename_file |
Rename or move a file. |
pending_changes |
List local edits not yet sent to Overleaf. |
Build and history
| Tool | Description |
|---|---|
compile |
Compile on Overleaf; returns distilled errors/warnings and the PDF link. |
publish_changes |
Push pending local edits to Overleaf. |
pull_project |
Re-download the project from Overleaf. |
edit_history |
Recent changes, each labelled with its operation id. |
undo_operation |
Reverse one specific operation, leaving everything after it in place. |
undo_last_edit |
Reverse the last N edits and republish. |
begin_change_set |
Open a change set: the edits that follow are published together, or not at all. |
commit_change_set |
Publish the open change set in one go. A failure leaves it open to retry. |
abandon_change_set |
Discard the open change set and return the mirror to the state it opened from. |
Review comments
| Tool | Description |
|---|---|
list_comments |
List comment threads with file and line. |
add_comment |
Add a comment, optionally anchored to a line. |
reply_to_comment |
Reply within a thread. |
resolve_comment |
Mark a thread resolved. |
Design notes
- Mirror plus per-file sync state. Each project has a locally cached, git-versioned mirror.
What Overleaf holds is recorded per file, as a content hash, rather than as one project-wide
ref: a single ref cannot describe a state where one file was refreshed while another still has
unpublished edits, and the version that tried made the pending file look published. Hashing
also keeps git out of the decision, so a failed
git addcan no longer produce a confident "nothing to publish". - One writer per project. Every mutating tool runs under that project's lock, so the whole refresh → read → write → commit → publish sequence is atomic with respect to other clients. Without it, two edits arriving together both read the same base and the second discards the first. Different projects stay fully concurrent. This serialises within one process; two server instances must not share a data directory.
- A partial publish is an error, not a footnote. If any file fails to reach Overleaf, the tool result is flagged as an error, because a warning inside an otherwise successful response is easy for a model to summarise away as "done" — and the user then believes their paper was updated.
- Edits can be pinned to a version.
read_filereports asha256:prefix andedit_fileaccepts it asexpected_hash, so an edit written against text that has since changed is refused rather than applied. Overleaf offers no atomic conditional write, so this cannot close the race between the check and the upload — but it turns the common case, "the user edited this after the model read it", into a conflict someone has to look at. - Change sets make a revision atomic. For work that spans several files, or that should not be visible half-finished,
begin_change_setsuspends publishing: the edits accumulate locally and reach Overleaf together oncommit_change_set. Without it a five-file revision arrives one file at a time, and anyone reading the paper in between sees a state that never existed as a whole.abandon_change_setdiscards the lot, and nothing was ever published, so there is nothing to undo remotely. - Every mutating call is an operation with an id. Results and
edit_historyreport it, andundo_operationreverses exactly that one, leaving later work alone. It reverts rather than resets, so the original edit stays in history and a mistaken undo is itself undoable. When a later edit has rewritten the same lines, the reversal is refused with the conflict reported — guessing which version was meant is how a tool destroys work it was asked to protect. - Undo is real. Every tool edit is a commit, and
undo_last_editusesgit revert, so an undo is itself undoable. It deliberately refuses to reverse a reload from Overleaf — that would push a stale copy over whatever you changed in the browser. - Freshness before use. A file is re-fetched from Overleaf before being read or edited
(whenever nothing is unpublished locally). If the text no longer matches, the edit fails
loudly. Costs one request per read; disable with
OLMCP_FRESH_READS=false. - Publish before compile. Compilation runs on Overleaf's servers, so pending edits are pushed first — otherwise "does it still compile?" would answer a question about the old file.
- Log distillation. A thesis log runs to thousands of lines of which about twenty matter, so
only errors (with
l.NNline references), undefined references, and warning counts survive. - Path safety. Every model-supplied path is validated against
.., absolute paths and drive letters, and zip entries that would escape the project root are skipped.
Configuration
All configuration is environment variables; see .env.example for the annotated
list. The essentials:
| Variable | Default | Purpose |
|---|---|---|
OVERLEAF_SESSION |
— | Required. The overleaf_session2 cookie value. |
PUBLIC_URL |
http://localhost:8080 |
Exact public HTTPS origin. OAuth metadata is built from it. |
MCP_AUTH_MODE |
bearer |
oauth, bearer, or none. Use oauth for the web clients. |
MCP_OAUTH_PASSWORD |
— | Required for oauth. The passphrase you type on the consent screen. |
MCP_BEARER_TOKENS |
— | Required for bearer. Comma-separated static tokens. |
OVERLEAF_BASE_URL |
https://www.overleaf.com |
Point at a self-hosted instance. |
OVERLEAF_EMAIL / OVERLEAF_PASSWORD |
— | Self-hosted only: silent re-login when the cookie expires. |
OLMCP_AUTO_PUSH |
true |
Publish each accepted edit immediately. |
OLMCP_READ_ONLY |
false |
Refuse every mutating tool. |
OLMCP_FRESH_READS |
true |
Re-fetch a file from Overleaf before reading or editing it. |
OLMCP_DATA_DIR |
./data |
Where project mirrors and OAuth state live. |
TRUST_PROXY |
1 |
Number of reverse proxies in front. Set to 0 if directly exposed. |
LOG_LEVEL |
info |
debug, info, warn, error. Logs go to stderr. |
Security model
This server is equivalent to remote write access to your Overleaf account. Treat it that way.
- Credentials. The session cookie lives in memory only. Every log line and every tool result passes through redaction, including the configured cookie value itself.
- Approval passphrase.
MCP_OAUTH_PASSWORDis the only thing standing between a stranger and your papers. The server refuses to start inoauthmode without it. - Callback allowlist. Dynamic client registration only accepts known vendor callbacks and loopback addresses. Without that, the server would be an open redirector handing out authorization codes.
- Tokens. Opaque and server-side, so revocation is immediate. Refresh tokens rotate, and replaying a rotated token revokes its whole chain.
- Least privilege.
OLMCP_READ_ONLY=truedisables every mutating tool, and OAuth scopes (overleaf.read,overleaf.write) let you hand out a read-only connection. - Rate limiting. Registration, token, and consent endpoints each have their own budget.
- Destructive operations.
delete_filerequires explicit confirmation, a push refuses to empty a project outright, and every edit is reversible.
Suggested rollout: start with OLMCP_READ_ONLY=true and let the assistant read for a while
before you grant write access.
LeafMCP MCP questions
What tools does LeafMCP MCP provide?
It exposes 26 tools, including list_projects, use_project, project_overview, list_files, read_file.
How do I connect LeafMCP to my Overleaf account?
You need to obtain your Overleaf session cookie (overleaf_session2) and provide it to the server configuration.
Does the server support undoing edits?
Yes, the server includes an undo tool that uses git reverts to reverse recent changes.
Is it possible to run this locally without a public URL?
Yes, local clients like Cursor or Claude Desktop can connect using the stdio transport without needing a public address.