overleaf-mcp-server

Overleaf MCP サーバー

Git 同期を通じて Overleaf プロジェクトを管理する MCP サーバーです。

PyPI パッケージ · MCP Registry

このサーバーの機能

• Git 同期を通じて、MCP 対応クライアントを Overleaf プロジェクトに接続します。
• プロジェクトのコンテンツを一覧表示、読み取り、書き込み、同期するファイル単位のツールを提供します。
• 最新ファイルを取得して編集し、Overleaf にプッシュするだけのシンプルなワークフローを実現します。

アーキテクチャ

flowchart LR
  C[MCP Client\nClaude Desktop / other MCP host] -->|Tool Call| S[Overleaf MCP Server]
  S -->|Git Sync| O[Overleaf Git Remote]
  S -->|Read / Write| L[Local Repo Mirror]
  L -->|Commit + Push| O
  O -->|Pull / Fetch| L
  S -->|Tool Result| C

ツールのワークフロー

sequenceDiagram
  participant Client as MCP Client
  participant Server as Overleaf MCP Server
  participant Local as Local Mirror
  participant Overleaf as Overleaf Git

  Client->>Server: list_files / read_file
  Server->>Local: Ensure local clone
  Server->>Overleaf: git pull
  Overleaf-->>Server: latest content
  Server-->>Client: file list / file content

  Client->>Server: write_file(path, content)
  Server->>Local: update file
  Server->>Local: git commit
  Server->>Overleaf: git push
  Server-->>Client: success + metadata

必要条件

• Python 3.13+
• uv パッケージマネージャー
• Git 統合が利用できる Overleaf プラン（個人、グループ、または機関ライセンス）。所属機関が無料アクセスを提供しているか、Overleaf for Institutions で確認してください。所属機関のメールアドレスを使用してください。所属機関が掲載されていない場合は、プランをアップグレードしてください。

Git のセットアップ

1. Git を有効にする - Overleaf でプロジェクトを開き、Menu → Integrations の Git を有効にします。
2. プロジェクト ID をコピーする - ブラウザーの URL からコピーします（例：https://www.overleaf.com/project/69a4f7cc4eaf13bd56de5b04 → 69a4f7cc4eaf13bd56de5b04）。
3. Git トークンを生成する - Account Settings → Git integration authentication tokens → Generate new token を選択します。
4. .env を設定する - .env.example を .env にコピーし、次の項目を入力します。

OVERLEAF_TOKEN=your_git_token
PROJECT_ID=your_project_id

project_id はツール呼び出しごとに渡すこともできますが、サーバーの設定には引き続き PROJECT_ID が必要です。

Overleaf の Git トークンは、アカウント全体で使用する認証情報です。MCP クライアントの環境または保護された .env ファイルにのみ保存し、漏えいした場合はローテーションしてください。

安全に関する注意事項

Overleaf プロジェクト内のファイルは、信頼できない入力です。.tex ファイルやプロジェクト設定には、モデルに向けた指示が含まれている可能性があります。ファイルの内容はコマンドではなくデータとして扱ってください。OVERLEAF_ALLOWED_PROJECTS を、サーバーがアクセスできるプロジェクトだけに制限してください。

OVERLEAF_ALLOWED_PROJECTS=project_id_a,project_id_b

デフォルトの許可リストには PROJECT_ID のみが含まれます。

クイックスタート

git clone https://github.com/younesbensafia/overleaf-mcp-server.git
cd overleaf-mcp-server
uv sync
cp .env.example .env   # then edit with your token/project id
uv run overleaf-mcp

チェックアウトせずに実行するには、Git バージョンを直接指定します。

uvx --from git+https://github.com/younesbensafia/overleaf-mcp-server overleaf-mcp

uvx overleaf-mcp をそのまま使用できるのは、プロジェクトを PyPI に公開した後のみです。

サーバーは stdio で待ち受けます。MCP クライアント（Claude Desktop など）を接続してください。

大規模なプロジェクトでは、まず sync_project を呼び出してください。初回の Git クローンには、MCP クライアントの個別のツールリクエストのタイムアウトを超える時間がかかる場合があります。

利用可能なツール

ツール	説明
list_files	Overleaf プロジェクトからファイルを取得して一覧表示します
read_file	ファイルの内容を読み取ります
write_file	テキストファイル全体を上書きし、コミットして Overleaf にプッシュします
edit_file	完全一致するテキストを置換し、コミットして Overleaf にプッシュします
sync_project	Overleaf から強制的にプル／同期します

read_file では、サイズの大きなドキュメントを分割して読み取るために、オプションの 0 始まりの offset と、上限付きの limit 行パラメーターを指定できます。

Claude Desktop のセットアップ

~/.config/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "overleaf": {
      "command": "uv",
      "args": ["--directory", "/path/to/overleaf-mcp-server", "run", "overleaf-mcp"],
      "env": {
        "OVERLEAF_TOKEN": "your_git_token",
        "PROJECT_ID": "your_project_id"
      }
    }
  }
}

トラブルシューティング

• Git 操作で 403 Forbidden が発生する場合：
  • ご利用のプランに Git 統合が含まれていません。Git のセットアップのセクションに従ってください。
  • または、Git トークンが間違っています。Account Settings → Git integration authentication tokens から再生成してください。
• プロジェクトの内容が違う場合：
  • .env で正しい PROJECT_ID を設定してください。
  • または、ツール呼び出しで project_id を明示的に渡してください。
• 同期の競合が発生する場合：
  • リモート側に変更がある場合は、write_file の前に sync_project を実行してください。
• サーバーが起動しない場合：
  • uv sync で依存関係がインストールされていることを確認してください。
  • Python 3.13+ が利用可能であることを確認してください。

License

MIT - See LICENSE