# 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.

```bash
npm install
npx playwright install chromium
npm run build
```

Run the published package with:

```bash
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:

```text
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

```text
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

```toml
[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