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="[email protected]" \
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

overleaf_compile always inspects output.log: a rendered PDF does not prove that LaTeX completed without errors. If the log contains an error, it clears cached files and retries once; persistent errors return parsed diagnostics plus the compiler log. Successful results may still contain warnings.

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 = "[email protected]",
  OVERLEAF_PASSWORD = "yourpassword",
  OVERLEAF_DATA_DIR = "/absolute/path/to/your/overleaf-paper-mcp-data"
}
startup_timeout_sec = 120
tool_timeout_sec = 120

License

MIT