Overleaf MCP サーバー

Git 統合を通じて Overleaf プロジェクトへのアクセスを提供する MCP (Model Context Protocol) サーバーです。これにより、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 — Windows 上の Claude Desktop では npx を見つけるために cmd /c が必要です：

{
  "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 ファイルをユーザー設定ディレクトリに配置し、Claude Desktop 設定の env ブロックを省略してください。

ファイルの場所

ファイルの内容

{
  "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"]
    }
  }
}

(macOS / Linux では cmd /c を削除してください。)

ツール呼び出しで projectName を指定して特定のプロジェクトを参照します：

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

projectName を省略した場合は、default エントリが使用されます。projects.json を標準以外の場所に配置したい場合は、env ブロックから OVERLEAF_PROJECTS_CONFIG=/absolute/path/projects.json を指定してください。

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 の代わり)。Claude Desktop の JSON にトークンを含めたくない場合に便利です。ファイルは起動時に一度読み込まれ、末尾の空白や改行は削除されます。

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 パッケージを利用せずに使用したい場合は、3 つのローカルインストールオプションがあります。

オプション 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 で tarball を指定します。明示的な --package= と bin 名に注意してください。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

stderr に Overleaf MCP server running on stdio と表示されるはずです。プロセスは stdin で JSON-RPC を待機したまま開いた状態になります。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: "..."

セキュリティ上の注意

• Overleaf Git トークンはプロジェクトへの完全な読み取り/書き込みアクセス権を付与します。パスワードのように扱ってください。

• 設定ファイルがバックアップや同期される場合は、Claude Desktop の JSON にトークンを直接記述するよりも OVERLEAF_GIT_TOKEN_FILE を優先してください。

• projects.json はこのリポジトリで .gitignore されています。実際のプロジェクト ID や Git トークンをコミットしないでください。

• MCP ツール呼び出しを通じて提供されるファイルパスは、クローンされたプロジェクトディレクトリ内に制限されています。.. によるトラバーサルや絶対パスは拒否されます。

ライセンス

MIT ライセンス