npm package: @iflow-mcp/ghoshsrinjoy-overleaf-mcp
Description: MCP server for Overleaf Git integration
Latest version: 1.0.0

![Overleaf MCP Server](assets/overleaf-mcp.png)
*Visualizing the bridge between Overleaf and AI through MCP*

*"I tried to argue with Overleaf, but it said my syntax was invalid."*

# Overleaf MCP Server  

An MCP (Model Context Protocol) server that gives Claude and other MCP clients access to Overleaf projects through Git integration. It can read LaTeX files, parse structure, and extract content ,  basically letting AI peek under the hood of your papers (ethically, of course). 🧠  

🔗 **Repo:** https://github.com/GhoshSrinjoy/Overleaf-mcp  

---

## Executive Summary  

This server bridges Overleaf and AI models through MCP. It lets clients list, read, and analyze LaTeX files as if Overleaf were a local workspace.  

Everything’s Git-based, so you get versioned, safe access. A Redis queue manages concurrency, keeping multiple project operations from stepping on each other.  

**In short:** It’s Overleaf → Git → Redis → MCP → Claude (or any client).  

---

## Business Problem  

Overleaf is great for collaboration, but hard to integrate with tools like Claude or LLM-based assistants. You either:  
- copy-paste LaTeX manually, or  
- mess with API endpoints and tokens in ways that don’t scale.  

This MCP server makes Overleaf “AI-readable.” It lets LLMs fetch content, inspect sections, and summarize papers without exposing tokens or corrupting repos. Perfect for research groups, AI note-takers, or publishing workflows.  

---

## Methodology  

**How it works**  
1. Uses Overleaf’s Git integration to clone and sync projects.  
2. Reads file trees and parses `.tex` documents for sections, subsections, and content.  
3. Dispatches jobs through a Redis-backed BullMQ queue.  
4. Each project gets its own Redis lock to prevent race conditions.  
5. Returns clean structured data through the MCP protocol.  

**Key features**  
- 📄 File management (list/read Overleaf files)  
- 📋 Document structure parsing (sections & subsections)  
- 🔍 Content extraction (get specific section by title)  
- 📊 Project summary (status, structure overview)  
- 🧩 Multi-project support  
- 🔒 Redis-backed queue for concurrency safety  
- 🕒 Git history & diff (refs or working tree) with truncation controls  
- ✏️ Safe edits: write files with optional commit/push, diff previews, and dry-run checks  

---

## Installation

1. Clone this repository
2. Install dependencies:
   ```bash
   npm install
   ```

3. Set up your projects configuration:
   ```bash
   cp projects.example.json projects.json
   ```

4. Edit `projects.json` with your Overleaf credentials:
   ```json
   {
     "projects": {
       "default": {
         "name": "My Paper",
         "projectId": "YOUR_OVERLEAF_PROJECT_ID",
         "gitToken": "YOUR_OVERLEAF_GIT_TOKEN"
       }
     }
   }
   ```

5. Start a Redis instance (locally or remotely). For example:
   ```bash
   docker compose up redis -d
   ```

6. Run the MCP server:
   ```bash
   npm start
   ```

## Getting Overleaf Credentials

1. **Git Token**: 
   - Go to Overleaf Account Settings → Git Integration
   - Click "Create Token"

2. **Project ID**: 
   - Open your Overleaf project
   - Find it in the URL: `https://www.overleaf.com/project/[PROJECT_ID]`

## Configuration & Environment

The server coordinates all tool calls through a Redis-backed BullMQ queue. Heavy Git operations are serialized per project using Redis locks to avoid repository corruption while still allowing concurrent work across different projects.

Key environment variables:

- `PROJECTS_FILE`: Path to the Overleaf project map (default: `./projects.json`).
- `OVERLEAF_TEMP_DIR`: Cache directory for cloned repositories (default: `./temp`).
- `REDIS_URL` **or** `REDIS_HOST`/`REDIS_PORT`/`REDIS_PASSWORD`/`REDIS_DB`: Redis connection details.
- `REQUEST_QUEUE_NAME`: Override the BullMQ queue name (default: `overleaf-mcp-requests`).
- `REQUEST_CONCURRENCY`: Worker concurrency for queued jobs (default: `4`).
- `REQUEST_TIMEOUT_MS`: Maximum time the server waits for a job to finish (default: `120000`).
- `PROJECT_LOCK_TTL_MS`, `PROJECT_LOCK_RETRY_MS`, `PROJECT_LOCK_MAX_WAIT_MS`: Advanced tuning for per-project Redis locks.
- `OVERLEAF_GIT_TOKEN`, `OVERLEAF_PROJECT_ID`: Optional environment fallbacks if they are not defined in `projects.json` or tool arguments.
- `HISTORY_LIMIT_DEFAULT`, `HISTORY_LIMIT_MAX`: Defaults for the `list_history` tool (defaults: 20 and 200).
- `DIFF_CONTEXT_LINES`, `DIFF_MAX_OUTPUT_CHARS`: Defaults for `get_diff`/`edit_file` previews (defaults: 3 and 120000).
- `OVERLEAF_GIT_AUTHOR_NAME`, `OVERLEAF_GIT_AUTHOR_EMAIL`: Git author/committer identity required for commits when using `edit_file`.

## Claude Desktop Setup

Add to your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/claude/claude_desktop_config.json`

### Option 1: Node.js Direct (Local Development)

```json
{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": [
        "/path/to/OverleafMCP/overleaf-mcp-server.js"
      ]
    }
  }
}
```

**Requirements**: Node.js installed locally, Redis running locally, all dependencies installed via `npm install`.

### Option 2: Docker Compose (Recommended for Production)

```json
{
  "mcpServers": {
    "overleaf": {
      "command": "docker",
      "args": ["compose", "run", "--rm", "-T", "mcp"],
      "cwd": "/path/to/OverleafMCP"
    }
  }
}
```

**Requirements**: Docker and Docker Compose installed, project built with `docker compose build`.
**Benefits**: Isolated environment, automatic Redis management, ephemeral containers.

### Option 3: Docker Exec (Persistent Container)

```json
{
  "mcpServers": {
    "overleaf": {
      "command": "docker",
      "args": ["exec", "-i", "CONTAINER_NAME", "node", "overleaf-mcp-server.js"]
    }
  }
}
```

**Example with specific container name**:
```json
{
  "mcpServers": {
    "overleaf": {
      "command": "docker",
      "args": ["exec", "-i", "overleaf_mcp-mcp-1", "node", "overleaf-mcp-server.js"]
    }
  }
}
```

**Requirements**: 
- Containers already running via `docker compose up -d`
- Replace `CONTAINER_NAME` with your actual container name (find with `docker ps`)
- Container must remain running for MCP to work

**When to use each approach**:
- **Option 1**: Development and debugging
- **Option 2**: Clean, isolated production deployments
- **Option 3**: When you want persistent containers and direct execution control

Restart Claude Desktop after configuration.

## Docker Usage

You can run the MCP server and its Redis dependency entirely in containers using the provided compose file.

### Basic Docker Setup

1. Copy `projects.example.json` to `projects.json` and fill in your credentials.
2. (Optional) Create a cache directory so clones persist across runs:
   ```bash
   mkdir -p data/cache
   ```
3. Build the containers:
   ```bash
   docker compose build
   ```
4. Start both Redis and MCP containers:
   ```bash
   docker compose up -d
   ```

### Advanced Docker Usage

**For ephemeral containers (Option 2 above)**:
```bash
# Start only Redis persistently
docker compose up -d redis

# MCP server will be started on-demand by Claude Desktop
```

**For persistent containers (Option 3 above)**:
```bash
# Start both services and keep them running
docker compose up -d

# Verify containers are running
docker compose ps

# Check container names for your configuration
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"
```

The compose service maps `projects.json` into the container at `/app/projects.json`, and stores cloned repos under `./data/cache` on the host.

Use `docker compose down` when you want to stop all containers.

### Container Management

**View container logs**:
```bash
# MCP server logs
docker compose logs mcp

# Redis logs  
docker compose logs redis

# Follow logs in real-time
docker compose logs -f mcp
```

**Troubleshooting container names**:
```bash
# List all containers with names
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"

# If using Option 3, update your Claude config with the correct container name
```

## Available Tools

### `list_projects`
List all configured projects.

### `list_files`
List files in a project (default: .tex files).
- `extension`: File extension filter (optional)
- `projectName`: Project identifier (optional, defaults to "default")

### `read_file`
Read a specific file from the project.
- `filePath`: Path to the file (required)
- `projectName`: Project identifier (optional)

### `get_sections`
Get all sections from a LaTeX file.
- `filePath`: Path to the LaTeX file (required)
- `projectName`: Project identifier (optional)

### `get_section_content`
Get content of a specific section.
- `filePath`: Path to the LaTeX file (required)
- `sectionTitle`: Title of the section (required)
- `projectName`: Project identifier (optional)

### `list_history`
Show recent git commits.
- `limit`: Maximum commits to return (default 20, max 200)
- `path`: Optional path filter
- `since` / `until`: git log time filters (e.g., `2.weeks`, `2025-01-01`)
- `projectName`: Project identifier (optional)

### `get_diff`
Get a git diff between refs or the working tree.
- `fromRef`: Base ref (omit to diff working tree vs HEAD)
- `toRef`: Target ref (omit to use working tree)
- `path` / `paths`: Optional path filters
- `contextLines`: Unified diff context lines (0-10, default 3)
- `maxOutputChars`: Truncate diff to this many characters (default 120000)
- `projectName`: Project identifier (optional)

### `edit_file`
Write a file and optionally commit/push the change.
- `filePath`: Target file path (required)
- `content`: New file content (required)
- `commitMessage`: Commit message (default: "Update via Overleaf MCP")
- `push`: Whether to push after committing (default: true)
- `dryRun`: If true, report sizes only; do not write or commit
- `contextLines` / `maxPreviewChars`: Diff preview controls
- `projectName`: Project identifier (optional)

### `status_summary`
Get a comprehensive project status summary.
- `projectName`: Project identifier (optional)

## Usage Examples

```
# List all projects
Use the list_projects tool

# Get project overview
Use status_summary tool

# Read main.tex file
Use read_file with filePath: "main.tex"

# Get Introduction section
Use get_section_content with filePath: "main.tex" and sectionTitle: "Introduction"

# List all sections in a file
Use get_sections with filePath: "main.tex"

# Show last 10 commits
Use list_history with limit: 10

# Show diff between HEAD and previous commit for main.tex
Use get_diff with fromRef: "HEAD~1", toRef: "HEAD", path: "main.tex", contextLines: 5

# Edit and push a file
Use edit_file with filePath: "sections/intro.tex", content: "<new text>", commitMessage: "Update intro", push: true
```

## Safeguards & limits
- Per-project Redis locks prevent concurrent git operations from colliding.
- Diff outputs are truncated by default (`maxOutputChars`, default 120k). Adjust per call as needed.
- History queries are capped (`limit`, default 20, max 200) to avoid timeouts.
- `edit_file` supports `dryRun` for size checks and returns a truncated diff preview; commits can skip pushes via `push: false`.
- All file writes go through path validation to stay inside the repo cache.

## Multi-Project Usage

To work with multiple projects, add them to `projects.json`:

```json
{
  "projects": {
    "default": {
      "name": "Main Paper",
      "projectId": "project-id-1",
      "gitToken": "token-1"
    },
    "paper2": {
      "name": "Second Paper", 
      "projectId": "project-id-2",
      "gitToken": "token-2"
    }
  }
}
```

Then specify the project in tool calls:
```
Use get_section_content with projectName: "paper2", filePath: "main.tex", sectionTitle: "Methods"
```

## File Structure

```
OverleafMCP/
├── Dockerfile                 # Container image for the MCP server
├── docker-compose.yml         # Docker Compose stack (server + Redis)
├── overleaf-mcp-server.js     # Main MCP server with Redis-backed queue
├── overleaf-git-client.js     # Git client library
├── package.json               # Dependencies and scripts
├── package-lock.json          # Exact dependency versions
├── projects.example.json      # Configuration template (copy to projects.json)
├── README.md                  # Documentation
└── .dockerignore              # Docker build context exclusions
```

## Troubleshooting

### Common Issues

1. **"Server disconnected" in Claude Desktop**:
   - Check container names with `docker ps`
   - Verify containers are running with `docker compose ps`
   - Check Redis connection with `docker compose logs redis`

2. **"Project does not exist" error**:
   - Verify Project ID in your Overleaf URL
   - Check Git Token is valid and not expired
   - Ensure Git integration is enabled in Overleaf project settings

3. **Redis connection errors**:
   - Ensure Redis container is running: `docker compose up -d redis`
   - Check Redis logs: `docker compose logs redis`

4. **Container name mismatch (Option 3 users)**:
   - Find correct container name: `docker ps --format "table {{.Names}}"`
   - Update Claude Desktop config with exact container name
   - Container names may include project directory prefix (e.g., `overleaf_mcp-mcp-1`)

### Why Redis is Important

Redis provides several critical functions:

- **Queue Management**: Handles multiple simultaneous requests without blocking
- **Project Locking**: Prevents Git conflicts when multiple operations access the same project
- **Worker Pool Management**: Distributes workload across multiple worker processes
- **Production Readiness**: Makes the server scalable and robust for concurrent usage

Without Redis, the server would work for single-user scenarios but could face race conditions and resource exhaustion under load.

## Security Notes

- `projects.json` is gitignored to protect your credentials
- Never commit real project IDs or Git tokens
- Use the provided `projects.example.json` as a template
- Container logs may contain sensitive information - secure appropriately

## Citation

If you use this software in your research, please cite:

```
@software{overleaf_mcp_2025,
  author = {GhoshSrinjoy},
  title = {Overleaf MCP Server},
  year = {2025},
  url = {https://github.com/GhoshSrinjoy/Overleaf-mcp}
}
```

## Skills  

This project touches on: Node.js, Redis (BullMQ), Docker, Overleaf Git integration, file parsing (LaTeX), concurrent job queues, and MCP protocol design.  
It also demonstrates practical engineering for AI × research integration — building bridges between human writing tools and model understanding. 🧩  

---

## Results & Business Recommendation  

**What it delivers**  
- Seamless Overleaf access for Claude and other MCP clients.  
- Structured reading of LaTeX files and sections.  
- Scalable multi-project handling via Redis queues.  
- No need to expose Overleaf APIs publicly or store plaintext tokens.  

**Best for:**  
- Research labs building paper assistants or summarizers.  
- AI tools integrating academic context.  
- Developers needing safe, concurrent Overleaf sync.  

**Recommendation:**  
Use **Docker Compose (Option 2)** for production : it keeps Redis and the MCP server isolated and persistent.  
For local testing, **Node Direct (Option 1)** is enough.  
Option 3 (Docker Exec) is great when you want persistent containers and direct control. 🎯  

---

## Next Steps  

🧠 Add smarter section extraction using regex or tree-based parsing.  
🧵 Add worker scaling for large document sets.  
🔒 Add encryption for cached repositories.  
🧩 Extend support for Markdown and BibTeX parsing.  
📦 Publish a prebuilt Docker image to Docker Hub.  
🧰 Add CI tests for Redis + lock integrity.  
🤖 Add optional Claude prompts for “auto-summarize LaTeX sections.”  

---
MIT License