Overleaf MCP Server

MCP-сервер (Model Context Protocol), предоставляющий доступ к проектам Overleaf через интеграцию с Git. Это позволяет Claude и другим MCP-клиентам читать LaTeX-файлы, анализировать структуру документа, извлекать содержимое, а также записывать файлы в проекты Overleaf и из них.

Возможности

• 📄 Управление файлами: список, чтение и запись файлов в проектах Overleaf

• 📋 Структура документа: разбор разделов и подразделов LaTeX

• 🔍 Извлечение содержимого: извлечение конкретных разделов по заголовку

• 📊 Сводка проекта: получение обзора состояния и структуры проекта

• 🏗️ Поддержка нескольких проектов: управление несколькими проектами Overleaf

Related MCP server: Overleaf MCP Server

Быстрый старт (рекомендуется)

Никакого клонирования, никакого npm install. Добавьте этот блок в конфигурацию Claude Desktop и перезапустите Claude Desktop.

Расположение файла конфигурации

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 на Windows требует cmd /c для поиска 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"
      }
    }
  }
}

Перезапустите Claude Desktop. Инструменты overleaf должны появиться в меню 🔧.

Настройка нескольких проектов

Быстрый старт через переменные окружения поддерживает только один проект. Для нескольких проектов поместите файл projects.json в директорию конфигурации пользователя и пропустите блок env в конфигурации Claude Desktop.

Расположение файла

Содержимое файла

{
  "projects": {
    "default": {
      "name": "Main Paper",
      "projectId": "...",
      "gitToken": "olp_..."
    },
    "thesis": {
      "name": "PhD Thesis",
      "projectId": "...",
      "gitToken": "olp_..."
    }
  }
}

Конфигурация Claude Desktop — то же самое, что и при быстром старте, но без блока env:

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

(Уберите cmd /c на macOS / Linux.)

Ссылайтесь на конкретный проект в вызовах инструментов с помощью projectName:

Use read_file with filePath: "main.tex", projectName: "thesis"

Если projectName опущен, используется запись default. Чтобы разместить projects.json не в стандартном месте, укажите путь к нему через OVERLEAF_PROJECTS_CONFIG=/absolute/path/projects.json в блоке env.

Получение учетных данных Overleaf

1. ID проекта — откройте ваш проект Overleaf; ID находится в URL: https://www.overleaf.com/project/[PROJECT_ID]

2. Git-токен — Overleaf → Account Settings → Git Integration → "Create Token"

Справочник по конфигурации

Сервер выбирает первый подходящий источник конфигурации:

1. Переменные окружения (один проект) — OVERLEAF_PROJECT_ID + OVERLEAF_GIT_TOKEN. Опционально: OVERLEAF_PROJECT_NAME для отображаемого имени.

2. Токен из файла — установите OVERLEAF_PROJECT_ID вместе с OVERLEAF_GIT_TOKEN_FILE=/path/to/token.txt (вместо OVERLEAF_GIT_TOKEN). Полезно, если вы не хотите хранить токен в JSON-файле Claude Desktop. Файл считывается один раз при запуске, все завершающие пробелы/символы переноса строки удаляются.

3. Файл для нескольких проектов — OVERLEAF_PROJECTS_CONFIG=/absolute/path/projects.json.

4. Директория конфигурации пользователя — projects.json в:

   • Windows: %APPDATA%\overleaf-mcp\projects.json

   • macOS / Linux: $XDG_CONFIG_HOME/overleaf-mcp/projects.json (по умолчанию ~/.config/overleaf-mcp/projects.json)

5. Рабочая директория — ./projects.json

6. Директория пакета — projects.json рядом со скриптом сервера (устаревший метод, для установок на основе клонирования).

Когда установлены переменные окружения и также присутствует файл, переменные окружения имеют приоритет, а в stderr записывается уведомление, чтобы было видно перекрытие.

Схема projects.json (несколько проектов)

{
  "projects": {
    "default": {
      "name": "Main Paper",
      "projectId": "...",
      "gitToken": "olp_..."
    },
    "paper2": {
      "name": "Second Paper",
      "projectId": "...",
      "gitToken": "olp_..."
    }
  }
}

Затем укажите проект в вызовах инструментов: projectName: "paper2".

Локальная разработка

Если вы хотите поработать над сервером, протестировать изменения перед публикацией или использовать его без доступного npm-пакета, у вас есть три варианта локальной установки.

Вариант 1 — Запуск клонированного скрипта напрямую

git clone https://github.com/mjyoo2/OverleafMCP.git
cd OverleafMCP
npm install

Затем укажите Claude Desktop путь к скрипту и передайте учетные данные через переменные окружения (тот же путь загрузчика, который использует npm-пакет):

{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": ["/absolute/path/to/OverleafMCP/overleaf-mcp-server.js"],
      "env": {
        "OVERLEAF_PROJECT_ID": "...",
        "OVERLEAF_GIT_TOKEN": "olp_..."
      }
    }
  }
}

На Windows в args следует использовать "C:\\Users\\you\\OverleafMCP\\overleaf-mcp-server.js".

Если вы предпочитаете использовать файл для нескольких проектов:

cp projects.example.json projects.json   # then edit it

projects.json рядом со скриптом является резервным вариантом с самым низким приоритетом, поэтому это работает и без переменных окружения.

Вариант 2 — Тестирование упакованного npm-артефакта локально

Проверяет практически тот же путь кода, с которым сталкиваются пользователи через публичный реестр, полезно перед выпуском релиза:

npm pack
# → mjyoo2-overleaf-mcp-<version>.tgz

Укажите Claude Desktop путь к tar-архиву. Обратите внимание на явный --package= и имя бинарного файла — npx -y <tarball-path> не работает в npm 10+ (путь ошибочно определяется как исполняемый файл):

{
  "mcpServers": {
    "overleaf": {
      "command": "cmd",
      "args": [
        "/c", "npx", "-y",
        "--package=C:\\absolute\\path\\to\\mjyoo2-overleaf-mcp-<version>.tgz",
        "overleaf-mcp"
      ],
      "env": {
        "OVERLEAF_PROJECT_ID": "...",
        "OVERLEAF_GIT_TOKEN": "olp_..."
      }
    }
  }
}

На macOS / Linux уберите обертку cmd /c: "command": "npx", "args": ["-y", "--package=/abs/path/to/...tgz", "overleaf-mcp"].

Вариант 3 — Дымовое тестирование протокола MCP из оболочки

Claude Desktop не требуется:

OVERLEAF_PROJECT_ID=... OVERLEAF_GIT_TOKEN=... node overleaf-mcp-server.js

Вы должны увидеть Overleaf MCP server running on stdio в stderr. Процесс остается открытым, ожидая JSON-RPC на stdin; Ctrl+C для выхода.

Доступные инструменты

list_projects

Список всех настроенных проектов.

list_files

Список файлов в проекте (по умолчанию: .tex файлы).

• extension: фильтр расширений файлов (опционально)

• projectName: идентификатор проекта (опционально, по умолчанию "default")

read_file

Чтение конкретного файла из проекта.

• filePath: путь к файлу (обязательно)

• projectName: идентификатор проекта (опционально)

get_sections

Получение всех разделов из LaTeX-файла.

• filePath: путь к LaTeX-файлу (обязательно)

• projectName: идентификатор проекта (опционально)

get_section_content

Получение содержимого конкретного раздела.

• filePath: путь к LaTeX-файлу (обязательно)

• sectionTitle: заголовок раздела (обязательно)

• projectName: идентификатор проекта (опционально)

status_summary

Получение полной сводки состояния проекта.

• projectName: идентификатор проекта (опционально)

write_file

Запись полного содержимого файла в проект.

• filePath: путь к файлу (обязательно)

• content: содержимое для записи в файл (обязательно)

• commitMessage: сообщение коммита (обязательно)

• projectName: идентификатор проекта (опционально)

write_section

Запись содержимого конкретного раздела в проект.

• filePath: путь к LaTeX-файлу (обязательно)

• sectionTitle: заголовок раздела (обязательно)

• newContent: новое содержимое для раздела, включая заголовок раздела (обязательно)

• commitMessage: сообщение коммита (обязательно)

• projectName: идентификатор проекта (опционально)

Примеры использования

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

# Write the full content of a file to the project
Use write_file with filePath: "main.tex", content: "...", commitMessage: "..."

# Write the content of a specific section to the project
Use write_section with filePath: "main.tex", sectionTitle: "Introduction", newContent: "\\section{Introduction}\n...", commitMessage: "..."

Примечания по безопасности

• Git-токен Overleaf предоставляет полный доступ на чтение/запись к вашему проекту — относитесь к нему как к паролю.

• Предпочитайте OVERLEAF_GIT_TOKEN_FILE вместо вставки токена в JSON-файл Claude Desktop, если ваш файл конфигурации резервируется или синхронизируется.

• projects.json добавлен в .gitignore в этом репозитории. Никогда не коммитьте реальные ID проектов или Git-токены.

• Пути к файлам, передаваемые через вызовы инструментов MCP, ограничены директорией клонированного проекта; перемещение через .. и абсолютные пути отклоняются.

Лицензия

MIT License