Overleaf Web MCP

Unofficial MCP server for browsing, tracked writing, organizing, compiling, reviewing, and monitoring version history in Overleaf projects through an authenticated web session.

Connect	Organize	Write	Compile	Review	History
Dedicated Chrome-family profile and saved session	Browse projects and manage files, folders, uploads, and downloads	Revision-checked whole-file and section edits, optionally tracked	Build a selected root document and stop active compiles	List, anchor, reply, resolve, and reopen comments	Poll recent project updates with a version cursor

Overleaf Web MCP is an independent Node.js Model Context Protocol server for complete Overleaf project workflows. It uses browser-facing private REST endpoints plus Socket.IO/OT through a saved web session, without requiring Overleaf Git integration.

Caution

This is an unofficial client for unsupported private APIs. Overleaf may change these interfaces without notice, and automating www.overleaf.com may carry Terms-of-Service and account risk. Start with a disposable project, keep live-test volume low, and review Overleaf's current terms before using an important account.

Quick start

Requirements:

• Node.js 20 or newer
• Google Chrome, Chromium, Brave, or Microsoft Edge for browser-assisted login
• An Overleaf account with access to the target projects

Install from npm and connect an MCP client

Capture and verify a session:

npx overleaf-web-mcp login

Configure an MCP client to start the package over stdio:

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "overleaf-web-mcp", "serve"]
    }
  }
}

The serve command is the default and can be omitted.

Run from a source checkout

From the repository root:

npm install
npm run build
npm run login
npm start

npm run login opens a dedicated browser window. Complete the normal Overleaf sign-in flow, including SSO or two-factor authentication when required. The window closes after authentication is detected, and the package saves only cookies applicable to the configured Overleaf origin.

Connect to self-hosted Overleaf

Use the same origin for login and the MCP server:

OVERLEAF_BASE_URL=https://overleaf.example.org npx overleaf-web-mcp login

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "overleaf-web-mcp", "serve"],
      "env": {
        "OVERLEAF_BASE_URL": "https://overleaf.example.org"
      }
    }
  }
}

Private API and feature availability varies by Overleaf deployment and edition.

Tools

The server registers 19 tools. Expand only the areas you need.

Account and connection — 2 tools

Tool	Purpose
auth_status	Verify the saved web session without exposing cookies
list_projects	List projects available to the authenticated account

Projects, files, and tracked writing — 7 tools

Tool	Purpose
get_project_tree	Return the current file and folder tree with paths and entity IDs
read_file	Read LF-normalized text and its opaque revision
write_file	Replace text through a minimal verified OT update; optionally use tracked changes
create_file	Create a text document and optionally track non-empty initial content
manage_entity	Create folders and rename, move, or confirmed-delete entities
upload_file	Upload a local binary file to a project folder
download_file	Download a document or binary file to an explicit local path

write_file and non-empty create_file content accept writeMode: "untracked" | "tracked". The default is "untracked" for backward compatibility. Tracked file creation requires non-empty initial content; creating the file entity itself remains a normal project-tree operation.

LaTeX sections — 3 tools

Tool	Purpose
get_sections	Parse section headings in one LaTeX file
get_section_content	Read one parsed section body
write_section	Replace one section body with a revision-checked tracked or untracked write

Section parsing is single-file only. It recognizes starred headings and optional titles, ignores % comments and common verbatim-like environments, and never follows \input or \include.

Compilation — 2 tools

Tool	Purpose
compile_project	Compile a project using a selected root document
stop_compile	Stop the active compile for a project

Review and replies — 4 tools

Tool	Purpose
list_comments	List and filter threads with lazy source-range resolution
reply_to_comment	Reply to an existing thread with timeout deduplication
add_comment	Create and verify a thread anchored to exact source text
set_comment_status	Resolve or reopen a thread and verify the resulting state

add_comment uses 1-based line and UTF-16 column positions. The normalized live selection must exactly equal expectedText.

Version history — 1 tool

Tool	Purpose
monitor_project_history	Poll one recent update window and return entries newer than an optional version cursor

This is stateless client-driven polling, not a background watcher. Results include currentVersion, nextSinceVersion, hasEarlierHistory, and gapDetected, plus normalized update groups with authors, paths, file-tree operations, labels, and origin metadata. Author emails and raw private response fields are omitted.

Key safety contracts:

• Reads normalize CRLF and lone CR to LF and report newline: "LF".
• Revisions are opaque concurrency tokens containing project and document identity, OT protocol, version, and a SHA-256 content hash. Callers should retain but never construct them.
• Content writes use minimal OT edits and are verified against a freshly joined document. Ambiguous writes are observed during a bounded recovery window and are never retried automatically.
• Explicit tracked writes never silently fall back to untracked writes. They require an authenticated user ID, while trackChangesActive separately reports the project state observed at connection time.
• manage_entity deletion requires confirmPath to exactly equal path.

Common workflows

Browse and organize a project

1. Call list_projects, then get_project_tree.
2. Use create_file for text, or manage_entity to create folders and rename, move, or confirmed-delete entities.
3. Use upload_file for local binaries and download_file to save documents or binaries to explicit local paths.

Make a safe tracked or untracked edit

1. Call read_file and retain its revision.
2. Modify the LF-normalized content.
3. Call write_file with the unchanged revision, complete replacement content, and the desired mode:

{
  "projectId": "0123456789abcdef01234567",
  "filePath": "main.tex",
  "revision": "opaque-revision-from-read-file",
  "content": "\\section{Introduction}\nRevised text.\n",
  "writeMode": "tracked"
}

4. If REVISION_CONFLICT is returned, read again and reconcile against the new content; never reuse the stale revision.

create_file and write_section accept the same writeMode choice and return the resulting revision. A no-op write returns successfully but creates no tracked record.

Poll recent version history

Call monitor_project_history without a cursor to establish the current window:

{
  "projectId": "0123456789abcdef01234567"
}

On the next poll, pass the previous nextSinceVersion as sinceVersion. Only update groups whose toVersion is newer are returned. If gapDetected is true, the cursor predates the single returned window; the tool deliberately does not page backward or calculate diffs.

Compile a project

1. Call compile_project with the selected root document.
2. Use stop_compile to stop an active compile.

Review and reply to comments

1. Call list_comments; it defaults to open threads and accepts file, status, and author filters.
2. Use reply_to_comment for an existing thread.
3. To anchor a new thread, call read_file, select an exact range, then pass its revision, UTF-16 positions, expectedText, and message to add_comment.
4. Pass the latest revision to set_comment_status when resolving or reopening an anchored thread.

All review-panel threads include available author metadata. Overleaf does not expose a reliable separate reviewer classification. Review comments and tracked changes require an Overleaf deployment and account entitlement that supports them.

Configuration, authentication, and security

The cookie jar is local, never returned by a tool, and protected with restrictive permissions where the filesystem supports them. The server reserves stdout for MCP protocol messages and does not log cookies, filenames, document content, diffs, quoted context, or review-message bodies.

Configuration reference

Variable	Default	Purpose
OVERLEAF_COOKIE_JAR_FILE	Platform configuration directory	Saved-session path override
OVERLEAF_BASE_URL	https://www.overleaf.com	Target Overleaf origin
OVERLEAF_BROWSER_PATH	Auto-detected	Chrome-family executable used by login
OVERLEAF_BROWSER_PROFILE_DIR	Platform configuration directory	Dedicated login profile
OVERLEAF_LOGIN_TIMEOUT_MS	300000	Browser sign-in deadline, capped at 15 minutes
OVERLEAF_PROTOCOL_VERSIONS	2	Comma-separated accepted collaboration protocol versions
OVERLEAF_MAX_DOC_LENGTH	2097152	Fallback maximum UTF-16 document length
OVERLEAF_MAX_UPDATE_CHARS	7340032	Conservative serialized OT update limit
OVERLEAF_SOCKET_CACHE_SIZE	2	Maximum cached project sockets
OVERLEAF_SOCKET_IDLE_TTL_MS	90000	Idle project-socket lifetime
OVERLEAF_REQUEST_TIMEOUT_MS	30000	REST and collaboration-call timeout
OVERLEAF_APPLY_TIMEOUT_MS	30000	OT acknowledgement and application timeout
OVERLEAF_RECOVERY_TIMEOUT_MS	30000	Ambiguous-mutation observation window
OVERLEAF_COMPILE_TIMEOUT_MS	120000	Default compile wait, capped at 15 minutes

An advertised ol-maxDocLength value takes precedence over the fallback. Target content at or above the limit returns DOC_TOO_LARGE; an oversized serialized update returns UPDATE_TOO_LARGE and must be split into smaller independently revisioned writes.

compile_project.timeoutMs accepts 1 second through 15 minutes. It changes only how long the MCP call waits, not the account's server-side compile allowance.

Authentication storage and refresh behavior

The login command uses a separate browser profile and does not inspect the normal Chrome profile. Session files are stored under overleaf-web-mcp in the platform configuration directory:

• Linux: ${XDG_CONFIG_HOME:-~/.config}/overleaf-web-mcp
• macOS: ~/Library/Application Support/overleaf-web-mcp
• Windows: %APPDATA%\overleaf-web-mcp

Only cookies applicable to OVERLEAF_BASE_URL are saved. On POSIX systems, the configuration directory uses mode 0700 and the cookie jar mode 0600; group- or world-readable jars are rejected. Filesystems without meaningful POSIX modes continue with a permissionsUnchecked warning.

Cookie refreshes are merged under an advisory lock and written through a protected temporary file followed by atomic replacement. If the session expires, run npx overleaf-web-mcp login again.

Technical details and ecosystem

Connection model and related projects

The entries below are representative rather than exhaustive, and their capabilities may change over time.

Implementation	Connection model	Focus
This project	Browser-assisted saved session plus private REST and Socket.IO/OT	Project/file management, tracked writing, compilation, review/replies, and recent history monitoring
@netique/overleaf-mcp	Browser session plus private REST and Socket.IO/OT	A close web/OT peer with review comments and tracked-change workflows
overleaf-mcp-rt	Session authentication plus native OT	Real-time file and compile tooling focused on self-hosted Community Edition
Git-based projects: OverleafMCP, overleaf-mcp-server, and vibeTeX	Primarily the Overleaf Git bridge	Git-backed synchronization, editing, and history workflows

Review-range investigation was informed by Overleaf Comment Exporter. Real-time protocol behavior was informed by Overleaf Workshop.

Protocol and reliability notes

• The collaboration adapter implements the Socket.IO 0.9 wire format used by the targeted Overleaf client family. Project bootstrap rejects unsupported protocol versions.
• ShareJS text OT and history-OT are normalized behind one document interface. Tracked ShareJS writes carry the authenticated author in update metadata; tracked history-OT writes carry author and timestamp metadata on inserted and retained-deletion components.
• Visible history-OT offsets account for tracked deletions retained in the raw snapshot.
• At most two project sockets are cached by default. Active sockets are never evicted, and idle sockets disconnect after 90 seconds. While a project socket remains open, the account may appear online to collaborators.
• All document sessions and tree mutations share a project-wide FIFO because Overleaf's join/leave epoch is socket-wide. Documents are joined for one queued operation and then left.
• A write succeeds only after acknowledgement, matching otUpdateApplied, leave/rejoin, and content-hash verification.
• If a write times out, the intended hash means success, the unchanged original revision means timeout, and any third observable state means conflict. The write is never submitted again automatically.
• A comment is created as a REST thread and then attached through OT. Timed-out attachment recovery checks the new thread ID and exact range; orphan cleanup occurs only after the unchanged document proves attachment did not apply.
• A timed-out reply is accepted only when current author, exact normalized content, and the request-time window identify the refreshed message.
• ShareJS comment status uses the dedicated REST action. History-OT comment status is part of the document operation and snapshot.
• History monitoring reads one 25-group update window, strips email fields, and keeps no cursor or background state on the server.

Protocol fixtures under test/fixtures/protocol are sanitized: cookies, user data, project and document IDs, and document content are removed.

Review-thread location behavior

Thread messages, authors, and resolution state come from /project/:id/threads. When the deployment exposes /project/:id/ranges, that project-wide index identifies the documents containing filtered threads. Only those documents are joined to calculate line and column positions and quoted context.

If a usable project-wide range index is unavailable, a project-wide call returns threads with positionsUnavailable: true; it never scans every document silently. Supplying filePath joins only that document and resolves its ShareJS ranges or history-OT comment state. Threads without a document range are returned as unlocated.

The discussion record and source range are separate Overleaf objects. The thread endpoint provides messages, while live document state provides attachment and status metadata.

Development

Local verification and gated live tests

npm run check
npm run lint
npm test
npm run build
npm pack --dry-run

Unit and deterministic integration tests cover revision identity, Unicode positions, section parsing, tracked and untracked OT operations, history normalization, update limits, queue/cache behavior, Socket.IO frames, timeout recovery, comment attachment, file-tree events, and MCP registration.

Live tests are disabled by default and must target a disposable project:

RUN_OVERLEAF_LIVE_TESTS=1 \
OVERLEAF_LIVE_TEST_PROJECT_ID=0123456789abcdef01234567 \
npm test -- test/live

Add RUN_OVERLEAF_LIVE_REVIEW_TESTS=1 for review reads, RUN_OVERLEAF_LIVE_TRACKED_WRITE_TESTS=1 for a disposable tracked file create/delete, or RUN_OVERLEAF_LIVE_HISTORY_TESTS=1 for read-only history normalization. Feature availability depends on the deployment and account. Keep request volume low and treat cleanup failures as test failures.

Current exclusions

Git workflows, collaborator/account administration, billing, chat, background history watching, backward history pagination, version diffs and restoration, label mutation, and editing or deleting individual comment messages are outside the current release. Private API compatibility is version-specific and maintained on a best-effort basis.

License

Licensed under the MIT License.