Overleaf MCP
Connect to Overleaf to inspect projects, read/watch and edit LaTeX source, upload/download files, review history/comments, and compile PDFs with version-checked writes.
Check session status, cookie renewal, and keepalive schedule.
List accessible projects and get a project's file tree and main document.
Read live text files, optionally by line range.
Watch files, wait for version changes, and stop watches.
Read invited collaborators and online presence.
Read project-wide comments, source anchors, and tracked changes (read-only in this schema).
Create empty text files and write/replace file content with document ID/version checks.
Upload local files with optional overwrite; download individual files and current/historical project ZIPs.
List project history, labels, and compare versions or file-tree differences.
Start remote/local/auto compilations and poll results for PDFs and logs.
Connects an MCP client to Overleaf projects, enabling reading live LaTeX source (whole files or line ranges), watching files for changes, creating and editing files with document ID and version checks, uploading and downloading files and source ZIPs, inspecting history and version labels and diffs, reading collaborators, comments and tracked changes, and compiling projects remotely on Overleaf or locally with a fallback mode to retrieve PDFs and logs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Overleaf MCP compile my thesis project and open the resulting PDF"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Overleaf MCP
English | 简体中文
Connect an MCP-compatible assistant to your Overleaf projects. Read live LaTeX files, edit source, upload attachments, inspect comments and history, and compile PDFs.
This is an unofficial, experimental integration. It runs locally over stdio and uses Overleaf's web endpoints and realtime connection. Changes to Overleaf may require updates here.
Features
Area | Supported features |
Projects | List accessible projects; browse files, folders and main-document settings |
Live reading | Read a whole text file or selected lines; watch changes and receive MCP resource notifications |
Editing | Create text files, replace exact text or write back a file with document ID and version checks |
Uploads | Upload local text, images, PDFs and other files; optionally overwrite existing files |
Downloads | Download individual files, complete source ZIPs and accessible historical versions |
History | Read change records, labels, file-tree differences and text differences |
Collaboration | Read invited members and online users |
Review | Read and create comments; reply, edit and delete messages; resolve, reopen and delete threads; accept and reject tracked changes |
Compilation | Compile on Overleaf or locally; retrieve the PDF and logs; fall back locally after remote timeouts or service errors |
Use a free Overleaf account with access to your projects. Available history, review actions and compilation follow the account and project permissions returned by Overleaf.
Related MCP server: overleaf-bridge
Quick start
You need:
Node.js 22 or newer, npm and Git.
Google Chrome installed locally.
An Overleaf account with access to the projects you want to use.
For local compilation only:
latexmkand the selected TeX engine. MacTeX or TeX Live can provide them.
Run directly from GitHub
Use npx to download, build and run the server:
npx --yes git+https://github.com/vvbbnn00/overleaf-mcp.git loginGit installation runs the package build script through npm and is tested with npm 10. Source installation provides direct control over dependency installation and building.
Sign in manually in the browser and complete any verification steps. After sign-in, the session is saved, the browser closes and the command exits. Your MCP client can then use the saved session.
Check the saved session:
npx --yes git+https://github.com/vvbbnn00/overleaf-mcp.git statusConnect your MCP client
For clients that use a mcpServers configuration, add:
{
"mcpServers": {
"overleaf": {
"command": "npx",
"args": ["--yes", "git+https://github.com/vvbbnn00/overleaf-mcp.git", "serve"]
}
}
}Login and the server share ~/.overleaf-mcp by default. Make npx and Node available on the MCP client's PATH, or configure the full path to npx. Use your client's configuration format.
Your MCP client starts the server and communicates with it over stdio.
Install from source
For development or a fixed local installation:
git clone https://github.com/vvbbnn00/overleaf-mcp.git
cd overleaf-mcp
npm ci
npm run build
npm run loginFor this installation, set the MCP command to node and its arguments to ["/absolute/path/to/overleaf-mcp/dist/cli.js", "serve"], using your checkout's actual path. Check the session with npm run dev -- status.
Using it
Start with list_projects to get a project ID, then get_project to see its files and folders. You can ask your assistant to:
Read
main.texand explain a section.Replace a specific paragraph while preserving the surrounding text.
Upload a figure into an existing project folder.
Show open comments and their source locations.
Compile the project and open the resulting PDF.
Find projects, files and history
list_projectsfilters by name substring (search), tag name,status(active,archivedortrashed), andownership(ownedorshared). Setlimitfor a page and passnextCursorascursorwith the same filters for the next page.search_filesmatches literal, case-sensitive text and returns the first hit on each matching line. UsepathPrefixfor a project-relative directory andextensionfor a suffix such as.tex.limitdefaults to 100 and accepts up to 500. Checktruncatedandunavailablefor incomplete results.list_historyfilters each page of update groups by exactpath,authorIdand the inclusive time windowsinceanduntil. Times accept ISO timestamps with a time zone or Unix milliseconds. PassnextBeforeTimestampasbeforeto continue, even if a filtered page has no matches. The CLI acceptsoverleaf-mcp history <id> [before].list_history_labelsfilters by exactversionand by a case-insensitive name substring (query).
Edit source
Read the file first. Pass its returned docId and version as expectedDocId and expectedVersion to write_file or replace_text.
replace_text confines edits to the single exact match of oldText. write_file compares lines first, then applies localized character edits. Both update affected comment ranges alongside source changes while preserving thread IDs, replies, and resolution status. Overleaf may merge concurrent edits.
The result separates three checks:
Field | Meaning |
| Overleaf confirmed that it applied the edit |
| A subsequent read found the same document at or beyond the confirmed version |
| The resulting text matches what you requested |
On VERSION_CONFLICT, read the file again. On WRITE_STATUS_UNKNOWN, reconnect the MCP server and inspect the document before deciding whether to retry. After this error, that connection rejects further writes to the document.
Upload files
Example arguments for upload_file:
{
"projectId": "PROJECT_ID",
"localPath": "/absolute/path/to/figure.png",
"path": "figures/figure.png",
"overwrite": false
}Replace PROJECT_ID and the file paths with your values. localPath refers to a file on the machine running this server. The destination folder must already exist. Omit path to use the local filename in the project root.
overwrite: falsekeeps existing files and requires a new destination name.overwrite: truereplaces a same-name text document or binary file. Usewrite_filefor text edits that require a version match.
The response includes the saved path, hashes and verification status. Overleaf may normalize text encoding or line endings. Check uploaded and verified before retrying; the returned path identifies the saved file, including a temporary upload awaiting its final rename. ZIP uploads are saved as project attachments.
Compile and download
Call compile_project with a project ID and a mode:
Mode | Behavior |
| Use Overleaf's compiler |
| Download the current source and use local TeX tools |
| Try Overleaf first; use local compilation after a timeout or eligible service error |
The call returns a jobId. Poll get_compile_result until the job finishes. state: completed marks the end of the job; result.status: success confirms successful compilation. LaTeX errors are returned with compiler logs for correction.
PDFs, logs and downloads are returned as MCP resources and local file paths. Preview support depends on your MCP client. Source ZIPs and compiled PDFs are separate downloads. Job IDs last for the current server process; saved files remain on disk.
Comments and tracked changes
Use list_comment_threads with resolved: false for open threads or resolved: true for resolved threads. Filter further by threadId or exact file path. A file-scoped result includes source ranges. Omit path when looking for threads without a source anchor.
Pass trackedChanges: {} to get_review for tracked changes only. The object also accepts kind (insert or delete) and authorId.
Start with read_file and get_review. For document edits, copy docId to expectedDocId and version to expectedVersion from the latest result for that file.
Use
create_commentwith aquotethat appears once in the file and your commentcontent.Use
reply_to_commentto reply. Useedit_comment_messageordelete_comment_messageto manage individual messages. GetthreadIdfrom the thread entry andmessageIdfrom the message'sidinget_review.Use
resolve_comment_thread,reopen_comment_threadanddelete_comment_threadwith the thread'spathandthreadId.Use
accept_tracked_changesorreject_tracked_changeswith the file's current document ID and version. Selectidvalues from itstrackedChangesentries and pass them aschangeIds.
posted: true confirms message acceptance; anchored: true confirms source placement for a new comment. Other review writes report applied, followed by a readback result in verified. readBackError describes the follow-up read. Refresh get_review to inspect the current result and decide whether to retry.
Tool reference
Tool | Purpose |
| Check login, observed session renewal and the next keepalive |
| Filter and page through accessible projects |
| Get the file tree, folder IDs and main document |
| Read current text, optionally by line range |
| Find literal text across project files |
| Start watching a text file |
| Wait up to 30 seconds for a different version or document |
| Stop a tool-created watch |
| Create an empty text file |
| Write text with document ID and version checks |
| Replace one exact occurrence with version checks |
| Upload a local file with optional overwrite |
| Download a text file or binary attachment |
| Download a current or historical source ZIP |
| Read available history records and pagination data |
| Read available version labels |
| Compare project versions or a file within them |
| Read invited members and current online users |
| Read comments, source positions and visible tracked changes |
| Filter comment threads by resolution, file or thread ID |
| Reply to an existing review comment thread |
| Create a comment attached to source text |
| Edit a comment or reply message |
| Delete a comment or reply message |
| Mark a comment thread as resolved |
| Reopen a resolved comment thread |
| Delete a comment thread and its source annotation |
| Accept selected tracked changes |
| Reject selected tracked changes |
| Start a remote, local or automatic compile job |
| Get a job's status and output files |
Use project-history versions from the history tools to compare or download historical projects. A file's version identifies its current text revision for source and review edits.
get_collaboration returns invited members and online users. Collaborators using shared links appear among online users while connected. In get_review, path selects the file for source annotations and tracked changes; threads contains the project-wide comment threads.
Use include: "members" or include: "presence" in get_collaboration to request either part separately.
Configuration and local data
Environment variable | Default | Purpose |
|
| Overleaf instance to connect to |
|
| Session, downloads and local build files |
|
| Browser channel passed to Playwright |
Use a separate state directory for each account or Overleaf instance.
Earlier checkouts saved sessions in the repository's .overleaf-mcp directory. To reuse that session, set OVERLEAF_STATE_DIR to the directory's absolute path in both your shell and MCP client configuration.
The state directory contains session cookies and project files. Keep access private and exclude the directory from version control. On POSIX systems, the directory uses mode 0700 and the session file uses 0600. The session file stores reusable login cookies as plain JSON.
When requests extend the session expiry, the running server schedules keepalive requests at intervals of up to 6 hours. Keep the server running for keepalive, and sign in again when the session is revoked.
Runtime behavior
Live reads return text synchronized to Overleaf. Watches report the latest snapshot and version; several rapid edits may arrive in one notification.
Legacy source and annotation operations support BMP Unicode, including Chinese. The
history-otprotocol also supports supplementary Unicode characters.Local compilation uses
latexmkto run pdfLaTeX, XeLaTeX or LuaLaTeX. Thelatexmkcommand uses-norcand-no-shell-escape. macOS addssandbox-execwhen available; other systems run the compiler as a local process. Choose trusted projects for local compilation.Uploads use the advertised server size limit, with a default of 50 MiB. Keep destination filenames under 150 characters.
Downloads and expanded ZIPs allow up to 512 MiB and 10,000 archive entries. Downloads buffer in memory. MCP embeds resources up to 32 MiB; use the local path for larger files.
The primary validation environment is macOS with the official Overleaf service.
Development
npm run check
npm test
npm run buildLocal tests run offline. Live checks in scripts/ use a saved session. Run node scripts/smoke.mjs PROJECT_ID main.tex for a read-only check.
The write checks, scripts/features-smoke.mjs and scripts/upload-smoke.mjs, require a fresh disposable project named TestForMCP. The feature check expects a compilable main.tex, a JPEG named frog.jpg, accessible initial history, and a comment attached to main.tex. These scripts create temporary project data and remove it when they finish; interrupted runs may need manual cleanup.
When reporting a problem, include the tool name, operating system, Node version and a redacted error summary. Remove cookies, session files, sharing tokens and private project content from the report.
License
MIT.
Available Tools
20 toolscompile_projectA
Start compilation and return a job ID immediately. mode=auto tries Overleaf first and falls back locally for timeout/service errors. Local compilation needs latexmk and the selected engine. Poll get_compile_result for this build PDF and logs.
Inputs: projectId (required), mode, compiler, rootPath, +1 more.
create_fileA
Create an empty editable text file. name is a filename, not a path. Omit parentFolderId for the project root. Then use write_file to populate it.
Inputs: name (required), projectId (required), parentFolderId.
download_fileCRead-only
Download a text file or binary attachment as a local artifact. Text documents come from a fresh live snapshot.
Inputs: path (required), projectId (required).
download_projectARead-only
Download the complete current source ZIP, or an API-accessible historical project version. historyVersion is a project-history version, not a document OT version.
Inputs: projectId (required), historyVersion.
get_collaborationARead-only
Read explicitly invited members and current online users separately. Link collaborators may appear only in presence, so invitedMembers is not a complete participant list. Online connections are grouped by account; unavailable presence is reported as unknown.
Inputs: projectId (required).
get_compile_resultARead-only
Get compilation job state, PDF/log artifact URIs and the actual compile status. state=completed means the job finished; result.status determines whether compilation succeeded.
Inputs: jobId (required).
get_history_diffARead-only
Compare two project-history versions. With path, returns file content differences; without path, returns file-tree differences. Use versions returned by list_history.
Inputs: to (required), from (required), projectId (required), path.
get_projectBRead-only
Get the live project file tree and main document.
Inputs: projectId (required).
get_reviewARead-only
Read project-wide comments, replies and resolution status, plus file/line anchors and visible tracked changes. path limits the annotation scan to one text file; threads remain project-wide. Data is limited by server permissions.
Inputs: projectId (required), path.
get_session_statusARead-only
Check the saved browser session, observed cookie renewal and keepalive schedule. Never returns cookie values.
Inputs: no named parameters.
list_historyCRead-only
Return the history API response unchanged. No local time-window restriction or subscription filtering is applied. Pass the server pagination cursor as before.
Inputs: projectId (required), before.
list_history_labelsBRead-only
Return project version labels visible to the current session, without local plan restrictions.
Inputs: projectId (required).
list_projectsARead-only
List projects accessible to the signed-in account, using the server response.
Inputs: no named parameters.
read_fileARead-only
Read a text file directly from the live document server. Each call obtains a fresh snapshot and version, not a ZIP or disk cache. Optional 1-based line range.
Inputs: path (required), projectId (required), endLine, startLine.
replace_textBDestructive
Replace exactly one occurrence of oldText in a file, preserving surrounding content. Requires a recent document ID and version. Reports confirmed application separately from final-content verification.
Inputs: path (required), newText (required), oldText (required), projectId (required), +2 more.
unwatch_fileARead-only
Stop a watch created by watch_file. Independent resource subscriptions and pending waits remain active.
Inputs: watchId (required).
upload_fileADestructive
Upload one local file to an existing project folder. localPath must be absolute on the MCP server. path is the project-relative destination, defaulting to the local basename. overwrite defaults to false; true explicitly permits replacing a same-name text document or binary file. Returns server acceptance, actual location and content verification separately. An unverified or unknown result must be inspected before retrying. ZIPs are uploaded as files, not imported as projects.
Inputs: localPath (required), projectId (required), path, overwrite.
wait_for_file_changeARead-only
Wait for a document version to change, up to 30 seconds. Returns the new content, or changed:false on timeout. Disconnections are reported explicitly.
Inputs: path (required), projectId (required), afterVersion (required), afterDocId, +1 more.
watch_fileBRead-only
Start watching server-pushed document changes. Use wait_for_file_change or subscribe to the returned resource URI.
Inputs: path (required), projectId (required).
write_fileADestructive
Replace text using OT edits that retain unchanged regions. Requires docId/version from a recent read. Rejects stale versions; waits for server application and verifies document identity and content. An unknown write outcome blocks further writes to that document on the connection; reconnect and inspect before retrying. Concurrent edits may be merged by Overleaf.
Inputs: path (required), content (required), projectId (required), expectedDocId (required), +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools target a clearly distinct resource+action (compile vs. get_compile_result, watch vs. wait vs. unwatch, list_history vs. list_history_labels vs. get_history_diff). The main fuzziness is between content-retrieval tools (read_file, download_file, get_project) and between the two editing tools (write_file, replace_text), though the descriptions do draw usable boundaries between them.
Every tool is snake_case verb_noun (get_session_status, list_projects, write_file, download_project, compile_project, watch_file, unwatch_file). Even the longer forms like wait_for_file_change and list_history_labels fit the same predictable pattern, so an agent can guess names reliably.
20 tools is on the heavy side but the surface genuinely spans several sub-domains (files, history, compilation, collaboration, review, session), so most tools earn their place. A few could plausibly be merged (e.g. watch/unwatch/wait as one polling tool), keeping it just short of a 5.
Core read/write/upload/download plus history and compilation are covered, but there is no way to create or delete a project, no delete/rename/move file operation, and the review surface is read-only (no posting comments or replies). These are notable gaps for an agent trying to do end-to-end project work rather than read-and-edit.
Maintenance
Related MCP Connectors
Project management shared by people and AI agents, with persistent project state through MCP.
Notes, files, GitHub, and Drive through one MCP connection.
Notes, files, GitHub, and Drive through one MCP connection.
Notes, files, GitHub, and Drive through one MCP connection.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to read, write, compile, and manage Overleaf projects through MCP, including file operations, project administration, and LaTeX compilation diagnostics.16MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to read, edit, upload, compile, and manage projects in a self-hosted Overleaf Community Edition via MCP, while also providing a git remote for cloning and pushing changes.1MIT
- AlicenseAqualityCmaintenanceEnables collaborative LaTeX editing on Overleaf with tracked changes, review comments, compilation, file management, and downloads via a single MCP connection.261AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables a writer and their AI tools to edit, compile, and manage self-hosted LaTeX projects through authenticated MCP tools, with revision-safe edits, file history, and isolated TeX compilation.MIT