Skip to content
Back to search

OverleafMCP

Model Context Protocol (MCP) server that lets AI assistants read Overleaf projects, parse LaTeX document structure, and push section-level edits back via Git. Compatible with Claude Desktop, Cursor, Windsurf, and any MCP client.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mjyoo2--overleafmcp/badge.svg)](/listings/mjyoo2--overleafmcp)

HTML

<a href="/listings/mjyoo2--overleafmcp"><img src="/api/listings/mjyoo2--overleafmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

No clone, no `npm install`. Add this block to your Claude Desktop config and restart Claude Desktop.

**Config file location**

| OS | Path | |---------|------| | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Linux | `~/.config/claude/claude_desktop_config.json` |

**macOS / Linux**

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["-y", "@mjyoo2/overleaf-mcp"],
      "env": {
        "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
        "OVERLEAF_GIT_TOKEN": "YOUR_OVERLEAF_GIT_TOKEN"
      }
    }
  }
}

**Windows** — Claude Desktop on Windows needs `cmd /c` to find `npx`:

{
  "mcpServers": {
    "overleaf": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@mjyoo2/overleaf-mcp"],
      "env": {
        "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
        "OVERLEAF_GIT_TOKEN": "YOUR_OVERLEAF_GIT_TOKEN"
      }
    }
  }
}

Restart Claude Desktop. The `overleaf` tools should appear in the 🔧 menu.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 315 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Overleaf MCP Server
  2. An MCP (Model Context Protocol) server that provides access to Overleaf projects via Git integration. This allows Claude and other MCP clients to read LaTeX files, analyze document structure, extract content, and write files from and to Overleaf projects.
  3. ## Features
  4. - 📄 **File Management**: List, read, and write files from and to Overleaf projects
  5. - 📋 **Document Structure**: Parse LaTeX sections and subsections
  6. - 🔍 **Content Extraction**: Extract specific sections by title
  7. - 📊 **Project Summary**: Get overview of project status and structure
  8. - 🏗️ **Multi-Project Support**: Manage multiple Overleaf projects
  9. ## Quick Start (recommended)
  10. No clone, no `npm install`. Add this block to your Claude Desktop config and restart Claude Desktop.
  11. **Config file location**
  12. | OS | Path |
  13. |---------|------|
  14. | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
  15. | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
  16. | Linux | `~/.config/claude/claude_desktop_config.json` |
  17. **macOS / Linux**
  18. ```json
  19. {
  20. "mcpServers": {
  21. "overleaf": {
  22. "command": "npx",
  23. "args": ["-y", "@mjyoo2/overleaf-mcp"],
  24. "env": {
  25. "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
  26. "OVERLEAF_GIT_TOKEN": "YOUR_OVERLEAF_GIT_TOKEN"
  27. }
  28. }
  29. }
  30. }
  31. ```
  32. **Windows** — Claude Desktop on Windows needs `cmd /c` to find `npx`:
  33. ```json
  34. {
  35. "mcpServers": {
  36. "overleaf": {
  37. "command": "cmd",
  38. "args": ["/c", "npx", "-y", "@mjyoo2/overleaf-mcp"],
  39. "env": {
  40. "OVERLEAF_PROJECT_ID": "YOUR_OVERLEAF_PROJECT_ID",
  41. "OVERLEAF_GIT_TOKEN": "YOUR_OVERLEAF_GIT_TOKEN"
  42. }
  43. }
  44. }
  45. }
  46. ```
  47. Restart Claude Desktop. The `overleaf` tools should appear in the 🔧 menu.
  48. ## Multi-Project Setup
  49. The env-var Quick Start only handles a single project. For multiple projects, drop a `projects.json` file into the user config directory and skip the `env` block in your Claude Desktop config.
  50. **File location**
  51. | OS | Path |
  52. |-----------------|------|
  53. | Windows | `%APPDATA%\overleaf-mcp\projects.json` |
  54. | macOS / Linux | `~/.config/overleaf-mcp/projects.json` (or `$XDG_CONFIG_HOME/overleaf-mcp/projects.json` if set) |
  55. **File contents**
  56. ```json
  57. {
  58. "projects": {
  59. "default": {
  60. "name": "Main Paper",
  61. "projectId": "...",
  62. "gitToken": "olp_..."
  63. },
  64. "thesis": {
  65. "name": "PhD Thesis",
  66. "projectId": "...",
  67. "gitToken": "olp_..."
  68. }
  69. }
  70. }
  71. ```
  72. **Claude Desktop config** — same as Quick Start but no `env` block:
  73. ```json
  74. {
  75. "mcpServers": {
  76. "overleaf": {
  77. "command": "cmd",
  78. "args": ["/c", "npx", "-y", "@mjyoo2/overleaf-mcp"]
  79. }
  80. }
  81. }
  82. ```
  83. (Drop `cmd /c` on macOS / Linux.)
  84. Reference a specific project in tool calls with `projectName`:
  85. ```
  86. Use read_file with filePath: "main.tex", projectName: "thesis"
  87. ```
  88. If `projectName` is omitted, the `default` entry is used. To put `projects.json` somewhere other than the standard location, point `OVERLEAF_PROJECTS_CONFIG=/absolute/path/projects.json` at it from the `env` block.
  89. ## Getting Overleaf Credentials
  90. 1. **Project ID** — open your Overleaf project; the ID is in the URL: `https://www.overleaf.com/project/[PROJECT_ID]`
  91. 2. **Git Token** — Overleaf → Account Settings → Git Integration → "Create Token"
  92. ## Configuration Reference
  93. The server picks the **first** matching configuration source:
  94. 1. **Env vars (single project)** — `OVERLEAF_PROJECT_ID` + `OVERLEAF_GIT_TOKEN`. Optional: `OVERLEAF_PROJECT_NAME` for the display name.
  95. 2. **Token from a file** — set `OVERLEAF_PROJECT_ID` together with `OVERLEAF_GIT_TOKEN_FILE=/path/to/token.txt` (instead of `OVERLEAF_GIT_TOKEN`). Useful when you don't want the token in the Claude Desktop JSON. The file is read once at startup and any trailing whitespace/newline is trimmed.
  96. 3. **Multi-project file** — `OVERLEAF_PROJECTS_CONFIG=/absolute/path/projects.json`.
  97. 4. **User config dir** — `projects.json` in:
  98. - Windows: `%APPDATA%\overleaf-mcp\projects.json`
  99. - macOS / Linux: `$XDG_CONFIG_HOME/overleaf-mcp/projects.json` (defaults to `~/.config/overleaf-mcp/projects.json`)
  100. 5. **Working directory** — `./projects.json`
  101. 6. **Package directory** — `projects.json` next to the server script (legacy, for clone-based installs).
  102. When env vars are set and a file is also present, env vars win and a notice is logged to stderr so the shadowing is visible.
  103. ### `projects.json` schema (multi-project)
  104. ```json
  105. {
  106. "projects": {
  107. "default": {
  108. "name": "Main Paper",
  109. "projectId": "...",
  110. "gitToken": "olp_..."
  111. },
  112. "paper2": {
  113. "name": "Second Paper",
  114. "projectId": "...",
  115. "gitToken": "olp_..."
  116. }
  117. }
  118. }
  119. ```
  120. Then specify the project in tool calls: `projectName: "paper2"`.
  121. ## Local Development
  122. If you want to hack on the server, test changes before publishing, or use it without the npm package being available, you have three local-install options.
  123. ### Option 1 — Run the cloned script directly
  124. ```bash
  125. git clone https://github.com/mjyoo2/OverleafMCP.git
  126. cd OverleafMCP
  127. npm install
  128. ```
  129. Then point Claude Desktop at the script and pass credentials via env vars (the same loader path the npm package uses):
  130. ```json
  131. {
  132. "mcpServers": {
  133. "overleaf": {
  134. "command": "node",
  135. "args": ["/absolute/path/to/OverleafMCP/overleaf-mcp-server.js"],
  136. "env": {
  137. "OVERLEAF_PROJECT_ID": "...",
  138. "OVERLEAF_GIT_TOKEN": "olp_..."
  139. }
  140. }
  141. }
  142. }
  143. ```
  144. On Windows, `args` should use `"C:\\Users\\you\\OverleafMCP\\overleaf-mcp-server.js"`.
  145. If you'd rather use a multi-project file:
  146. ```bash
  147. cp projects.example.json projects.json # then edit it
  148. ```
  149. `projects.json` next to the script is the lowest-priority fallback, so this still works without env vars.
  150. ### Option 2 — Test the packed npm artifact locally
  151. Validates almost the same code path users hit through the public registry, useful before pushing a release:
  152. ```bash
  153. npm pack
  154. # → mjyoo2-overleaf-mcp-<version>.tgz
  155. ```
  156. Point Claude Desktop at the tarball. Note the explicit `--package=` and bin name — `npx -y <tarball-path>` does **not** work in npm 10+ (the path is mis-detected as an executable):
  157. ```json
  158. {
  159. "mcpServers": {
  160. "overleaf": {
  161. "command": "cmd",
  162. "args": [
  163. "/c", "npx", "-y",
  164. "--package=C:\\absolute\\path\\to\\mjyoo2-overleaf-mcp-<version>.tgz",
  165. "overleaf-mcp"
  166. ],
  167. "env": {
  168. "OVERLEAF_PROJECT_ID": "...",
  169. "OVERLEAF_GIT_TOKEN": "olp_..."
  170. }
  171. }
  172. }
  173. }
  174. ```
  175. On macOS / Linux drop the `cmd /c` wrapper: `"command": "npx", "args": ["-y", "--package=/abs/path/to/...tgz", "overleaf-mcp"]`.
  176. ### Option 3 — Smoke-test the MCP protocol from the shell
  177. No Claude Desktop required:
  178. ```bash
  179. OVERLEAF_PROJECT_ID=... OVERLEAF_GIT_TOKEN=... node overleaf-mcp-server.js
  180. ```
  181. You should see `Overleaf MCP server running on stdio` on stderr. The process stays open waiting for JSON-RPC on stdin; Ctrl+C to exit.
  182. ## Available Tools
  183. ### `list_projects`
  184. List all configured projects.
  185. ### `list_files`
  186. List files in a project (default: .tex files).
  187. - `extension`: File extension filter (optional)
  188. - `projectName`: Project identifier (optional, defaults to "default")
  189. ### `read_file`
  190. Read a specific file from the project.
  191. - `filePath`: Path to the file (required)
  192. - `projectName`: Project identifier (optional)
  193. ### `get_sections`
  194. Get all sections from a LaTeX file.
  195. - `filePath`: Path to the LaTeX file (required)
  196. - `projectName`: Project identifier (optional)
  197. ### `get_section_content`
  198. Get content of a specific section.
  199. - `filePath`: Path to the LaTeX file (required)
  200. - `sectionTitle`: Title of the section (required)
  201. - `projectName`: Project identifier (optional)
  202. ### `status_summary`
  203. Get a comprehensive project status summary.
  204. - `projectName`: Project identifier (optional)
  205. ### `write_file`
  206. Write the full content of a file to the project.
  207. - `filePath`: Path to the file (required)
  208. - `content`: Content to write to the file (required)
  209. - `commitMessage`: Commit message (required)
  210. - `projectName`: Project identifier (optional)
  211. ### `write_section`
  212. Write the content of a specific section to the project.
  213. - `filePath`: Path to the file (required)
  214. - `sectionTitle`: Title of the section (required)
  215. - `newContent`: Replacement content for the section, including the section heading (required)
  216. - `commitMessage`: Commit message (required)
  217. - `projectName`: Project identifier (optional)
  218. ## Usage Examples
  219. ```
  220. # List all projects
  221. Use the list_projects tool
  222. # Get project overview
  223. Use status_summary tool
  224. # Read main.tex file
  225. Use read_file with filePath: "main.tex"
  226. # Get Introduction section
  227. Use get_section_content with filePath: "main.tex" and sectionTitle: "Introduction"
  228. # List all sections in a file
  229. Use get_sections with filePath: "main.tex"
  230. # Write the full content of a file to the project
  231. Use write_file with filePath: "main.tex", content: "...", commitMessage: "..."
  232. # Write the content of a specific section to the project
  233. Use write_section with filePath: "main.tex", sectionTitle: "Introduction", newContent: "\\section{Introduction}\n...", commitMessage: "..."
  234. ```
  235. ## Security Notes
  236. - The Overleaf Git token grants full read/write access to your project — treat it like a password.
  237. - Prefer `OVERLEAF_GIT_TOKEN_FILE` over inlining the token in the Claude Desktop JSON if your config file is backed up or synced.
  238. - `projects.json` is `.gitignore`d in this repo. Never commit real project IDs or Git tokens.
  239. - File paths supplied through MCP tool calls are restricted to the cloned project directory; `..` traversal and absolute paths are rejected.
  240. ## License
  241. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.