overleaf-paper-mcp

MCP server for managing academic LaTeX projects in Overleaf: create projects, transfer files, compile documents, inspect compiler output, and download PDFs.

Install

Requirements: Node.js 20+ and Playwright Chromium.

npm install
npx playwright install chromium
npm run build

Run the published package with:

OVERLEAF_EMAIL="your@email.com" \
OVERLEAF_PASSWORD="yourpassword" \
npx -y @youzhijc/overleaf-paper-mcp

Configuration

Provide credentials as runtime environment variables; do not commit a .env file.

Variable	Purpose
OVERLEAF_EMAIL	Overleaf login email.
OVERLEAF_PASSWORD	Overleaf login password.
OVERLEAF_DATA_DIR	Recommended absolute root for all MCP-managed local resources. Downloads are kept in workspace/; browser login state is kept in browser-data/.
OVERLEAF_WORKSPACE_DIR	Legacy alternative for the workspace only. Use OVERLEAF_DATA_DIR for new configurations.

Use absolute paths for local_path and zip_path when possible. Relative paths are accepted only inside OVERLEAF_DATA_DIR/workspace (or the legacy OVERLEAF_WORKSPACE_DIR). With OVERLEAF_DATA_DIR, all local state is kept below one directory:

OVERLEAF_DATA_DIR/
├── workspace/      # downloaded project files and PDFs
└── browser-data/   # Overleaf login session and browser cache

Do not upload or share browser-data/: it can contain your Overleaf login session. Delete workspace/ to clear downloads, browser-data/ to sign out, or the full data directory to reset the MCP.

Workflow

overleaf_list_files (optional)
→ overleaf_download_file
→ edit the local file
→ overleaf_upload_file (overwrite: true when replacing a file)
→ overleaf_compile
→ overleaf_download_pdf

On a visible compilation failure, overleaf_compile clears cached files, retries once, and returns parsed diagnostics plus the compiler log if the retry also fails.

overleaf_upload_file currently writes to the project root. To import a full project archive, use overleaf_create_project_from_zip.

Tools

Tool	Purpose
ping	Check server availability.
overleaf_login / overleaf_logout	Start or close the browser session.
overleaf_list_projects / overleaf_open_project	Find or open a project.
overleaf_create_project	Create an empty project.
overleaf_create_project_from_zip	Create a project from a local ZIP archive.
overleaf_list_files	List project files and paths.
overleaf_download_file / overleaf_upload_file	Transfer one project file.
overleaf_create_folder / overleaf_create_file	Create empty root-level items.
overleaf_rename_file / overleaf_delete_file	Rename or delete a file.
overleaf_compile	Compile and, after a failed retry, return LaTeX diagnostics and output.log.
overleaf_download_pdf	Download the compiled PDF.

Codex configuration

[mcp_servers.overleaf-paper-mcp]
command = "npx"
args = ["-y", "@youzhijc/overleaf-paper-mcp"]
env = {
  OVERLEAF_EMAIL = "your@email.com",
  OVERLEAF_PASSWORD = "yourpassword",
  OVERLEAF_DATA_DIR = "/absolute/path/to/your/overleaf-paper-mcp-data"
}
startup_timeout_sec = 120
tool_timeout_sec = 120

License

MIT