Overleaf

Overleaf MCP サーバー — LaTeX 論文を安全に AI 編集

Claude Code、Claude Desktop、Codex、ChatGPT、Cursor、VS Code などの MCP クライアントを Overleaf に接続できます。論文をチャットウィンドウにコピー＆ペーストすることなく、 LaTeX プロジェクトの読み取り、検索、編集、コンパイル、レビューを行えます。

npx --yes [email protected] setup

編集内容は、明示的に公開するまでローカルクローンに保存されます。この Overleaf MCP サーバーは、 読み取りとプッシュのたびに、共同作業者が変更した内容を確認します。双方が同じ行を編集した場合、 プッシュを停止し、どちらか一方を選ぶのではなく、両方のバージョンを表示します。

Overleaf のセッション Cookie を任意で設定すると、編集内容を変更履歴付きの提案として送信し、 共著者が承認または却下できるほか、既存のレビュー画面も読み取れるようになります。通常の Git プッシュでは どちらも実現できません。

ワンクリックでインストールできる Claude Desktop バンドルをダウンロード または、上記のセットアップコマンドを使用して、Claude Code、Codex、Cursor、その他のローカル AI クライアントに導入してください。

---

独立したコミュニティプロジェクトです。Overleaf との提携や、同社による推奨を受けていません。

この Overleaf MCP サーバーを選ぶ理由

Overleaf MCP サーバーはいくつかあります。Overleaf の公式 Git ブリッジを使用するものの中では、 これが最も機能が充実しており、共著者が編集中の行をすでに変更している場合に上書きせず、 処理を停止する唯一のサーバーです。

• 競合が発生したら、共著者の段落ではなくプッシュを停止します。 読み取りとプッシュの前に、 Overleaf で何が変更されたかを毎回確認します。2つの編集が同じ行に影響する場合、push_changes は プッシュを拒否し、両方のバージョンを表示します。
• 18個のツールを備え、指示するまで内容が Overleaf に反映されることはありません。 セクション単位または 正確なテキストを指定して読み取り、検索、編集し、ファイルの追加、名前変更、削除を行い、ローカルで コンパイルし、差分を確認してから、明示的に公開できます。
• 編集内容を完成済みの文章ではなく、提案として送信できます。 任意で使える3つのツールは、 Git ブリッジではなく Overleaf のエディターと連携するため、変更内容はレビュー画面に届き、 共著者が承認または却下できます。Git プッシュではこれを実現できません。 変更履歴
• 必要がなければ、ターミナルは不要です。 Claude Desktop にはダウンロードしたバンドルからインストールでき、 Claude Code と Codex にはプラグインとしてインストールできます。
• トークンは一度だけ、権限モード 600 で1つのファイルに書き込まれます。 クライアント設定にトークンは保存されず、 公開されているプラグインには環境変数が一切宣言されていません。

関連プロジェクトでは、代替ツールを機能ごとに比較し、このサーバーで できないことについても率直に説明しています。

よくあるワークフローには、学術論文をセクションごとに改訂すること、大規模な LaTeX プロジェクトを検索すること、 参考文献一覧を確認すること、公開前にコンパイルすること、正確な差分をレビューすること、 編集内容を変更履歴付きの提案として Overleaf に送信することなどがあります。

インストール先

以下のどの方法でも、同じサーバーと同じ18個のツールを利用でき、明示的にプッシュするまでは編集内容はローカルに保持されます。お使いのクライアントに該当する行を選んでください。 変更履歴の追跡ツールは追加の3つのツールで、セッション Cookie を設定した場合にのみ表示されます。

クライアント	インストール方法
Claude Desktop	バンドルをダウンロードしてダブルクリックします。ワンクリック
Claude Code	このリポジトリをプラグインマーケットプレイスとして追加します。2つのコマンド
Codex CLI、デスクトップ、IDE 拡張機能	同じ方法で、Codex のコマンドを使います。2つのコマンド
Cursor	npx --yes mcp-server-overleaf setup。1つのコマンド
Visual Studio Code	.vscode/mcp.json にエントリーを追加します。ガイド
ChatGPT のウェブ版とデスクトップ版	外向き接続のみの Secure MCP Tunnel を使います。公開エンドポイントもポート開放も不要です。ガイド
MCP レジストリを参照するカタログ	io.github.yangzichao/mcp-server-overleaf として登録済みです。詳細
その他の MCP クライアント	npx --yes mcp-server-overleaf --stdio、または Streamable HTTP を使います。手動でのインストール
開発に使用しているマシン	ソースをチェックアウトします。ソースからのインストール

Claude Desktop ではパッケージ化されたバンドルを、Claude Code と Codex ではそれぞれプラグインを使用します。それ以外では、setup が同等の処理を行います。どの方法でも、最後の手順は同じです。トークンを Overleaf で検証し、権限モード 600 の単一ファイルに書き込み、クライアント設定にはシークレットを保持しません。

ガイド

• プロジェクトの設定と効率的な読み取りでは、独立した認証情報、スパースチェックアウト、リビジョンの読み取り、保護された編集について説明します。
• 関連プロジェクトでは、既存の代替手段と、共同作業者の安全性および復旧に重点を置く本プロジェクトの方針について説明します。
• リリースの手順と検証では、テスト済みの成果物、来歴、初回公開、その後の信頼された公開について説明します。
• Claude Desktop バンドルをインストールするでは、ワンクリックでインストールできる .mcpb 拡張機能の内容、ビルド方法、削除方法について説明します。
• Claude Code と Codex のプラグインをインストールするでは、2つのマーケットプレイスエントリーの内容、プラグインがトークンを保持せずに取得する方法、更新、削除、ビルドの方法について説明します。
• ローカルの MCP クライアントを Overleaf に接続するでは、Codex のデスクトップ版と CLI、Claude Code、Claude Desktop、Cursor、Visual Studio Code、ローカルの stdio、検証、トラブルシューティングについて説明します。
• Secure MCP Tunnel を使って ChatGPT を Overleaf に接続するでは、ローカルの stdio サーバーから ChatGPT のデスクトップ版およびウェブ版までの、プライベート接続全体について説明します。ワークスペースとの関連付け、最小権限の認証情報、検証、トラブルシューティングも含みます。

インストールされるもの

stdio または Streamable HTTP 経由で 18 個のツールを公開する MCP サーバーです。セッション Cookie によって変更履歴が有効になると、さらに 3 個のツールが追加されます。コアは 1 つ、トランスポートは 2 種類です。ツールの実装は同一で、異なるのはフレーミングだけです。setup はこのコンピューター上の AI クライアントに接続するもので、ほとんどの人に必要なコマンドはこれだけです。

Node 22.14 以降と PATH 上の git が必要です。Node 24 LTS を推奨します。compile_project にはさらに latexmk と TeX ディストリビューションが必要ですが、それ以外のツールはこれらがなくても動作します。

リリーステストの対象は macOS と Linux です。Windows の Git および TeX のワークフローは、まだ検証されていません。このサーバーはコマンドラインアプリケーションであり、インポート可能な JavaScript ライブラリではありません。

プロジェクトで Git 統合を利用できる必要があります。Overleaf の説明では、これはプロジェクト所有者のサブスクリプションが必要なプレミアム機能です。そのため、サブスクリプションを持つ人が所有するプロジェクトに招待された無料アカウントでも利用でき、サブスクリプションは個人、グループ、または機関向けのいずれでも構いません。ユーザー自身のプランが利用資格を失わせると伝えないでください。代わりに手順 3 で直接確認してください。

ワンクリックで Claude Desktop にインストールする

mcp-server-overleaf.mcpb をダウンロードしてダブルクリックします。Claude Desktop がインストールパネルを開き、以下の 2 つの値を尋ねて、サーバーを起動します。ターミナルも、Node のインストールも、ビルドも不要です。

• Overleaf プロジェクトのアドレス — Overleaf でプロジェクトを開き、アドレスバーから URL 全体をコピーします。
• Overleaf Git トークン — Git 統合の設定で https://www.overleaf.com/user/settings から生成します。Claude Desktop はこれをオペレーティングシステムのキーチェーンに保存します。

このバンドルには、サーバー npm が公開するものと同じものが含まれており、固定されたランタイム依存関係以外は何も含まれていません。Claude Desktop が動作する環境である macOS と Windows のみが対象です。それ以外のクライアントでは、以下のコマンドを使用してください。詳細は Claude Desktop バンドルのインストールを参照してください。

Claude Code または Codex プラグインとしてインストールする

トークンを一度だけ保存します。

npx --yes [email protected] setup --clients none

次に、Claude Code で実行します。

claude plugin marketplace add yangzichao/mcp-server-overleaf
claude plugin install overleaf@mcp-server-overleaf

または、Codex で実行します。

codex plugin marketplace add yangzichao/mcp-server-overleaf
codex plugin add overleaf@mcp-server-overleaf

クライアントを再起動してから、プロジェクト内のファイル一覧を表示するよう指示してください。

このローカル MCP サーバーが公開ディレクトリに登録されるまでは、両方のクライアントとも、このリポジトリのマーケットプレイスからインストールします。Claude Code は .claude-plugin/marketplace.json を読み込み、Codex は .agents/plugins/marketplace.json を読み込みます。どちらも同じ plugins/overleaf ディレクトリを参照します。このプラグインにはトークンが含まれず、環境変数も設定されません。最初のコマンドがトークンを ~/.config/overleaf-mcp/projects.json に書き込み、サーバーがそこから見つけるためです。公開ディレクトリでの審査は、このリポジトリを使ったインストールとは別に行われます。詳細は Claude Code および Codex プラグインのインストールを参照してください。

1 つのコマンドでインストール

npx --yes [email protected] setup

Node と git を確認し、プロジェクトとトークンを尋ねます。何かを書き込む前にトークンが Overleaf に届くことを確認し、このコンピューターで見つかったクライアント（Claude Code、Codex、Claude Desktop、Cursor）にサーバーを登録します。Overleaf がトークンを受け付けるまで何も書き込まないため、実行に失敗しても中途半端な設定は残りません。

必要なものは 2 つで、どちらもブラウザーから取得します。

• プロジェクトのアドレス。 Overleaf でプロジェクトを開き、アドレスバーから URL 全体をコピーします。読み取り専用の共有リンクは別物です。セットアップ時にその旨が示されるため、後になって失敗することはありません。
• git 認証トークン。 https://www.overleaf.com/user/settings の Git integration で生成します。入力中、トークンは画面に表示されません。

トークンはモード 600 で ~/.config/overleaf-mcp/projects.json に書き込まれ、それ以外の場所には保存されません。サーバーはこのファイルを自動的に見つけるため、クライアント設定にシークレットやそのパス、環境変数が含まれることはありません。デスクトップアプリはターミナルよりも PATH が大幅に制限された状態で起動するため、クライアントには npx ではなく、Node の絶対パスとエントリーポイントの絶対パスを登録します。

その後、Claude Desktop、Cursor、または Codex を再起動してください。Claude Code は次回の実行時に設定を読み込みます。続いて、アシスタントにプロジェクト内のファイルを一覧表示するよう頼んでください。

セットアップは対話なしでも実行できます。

printf '%s' "$OVERLEAF_TOKEN" | npx --yes [email protected] setup \
  --project paper=https://www.overleaf.com/project/64a1b2c3d4e5f6a7b8c9d0e1 \
  --token-stdin --yes

--clients claude-code,codex を指定すると、設定対象のクライアントを絞り込めます。--clients none を指定すると、クライアントへの登録を行わずに設定を書き込みます。別のプロジェクトを追加したり、期限切れのトークンを置き換えたりするには、再度実行してください。以前のファイルはそのまま保持されます。

MCP レジストリで見つける

このサーバーは、公式の Model Context Protocol レジストリに io.github.yangzichao/mcp-server-overleaf として掲載されています。掲載情報には npm パッケージと Claude Desktop バンドルが記載されており、レジストリを参照するクライアントやカタログは、そこから情報を取得します。リリースワークフローで掲載情報自体を公開するため、npm に存在しないバージョンを指すことはありません。

Claude Code と Codex はそのレジストリを参照しません。これらには上記のセクションで説明した独自のプラグインマーケットプレイスがあります。または、サーバーを手動で追加できます。

claude mcp add --transport stdio --scope user overleaf -- npx --yes [email protected] --stdio
codex mcp add overleaf -- npx --yes [email protected] --stdio

どちらの形式でも、環境変数に OVERLEAF_GIT_TOKEN と OVERLEAF_PROJECT_ID が必要です。そのため、setup は代わりに projects.json を書き込み、絶対パスを登録します。

npm から手動でインストール

すべての手順を確認したい場合や、クライアント設定ガイドに記載のない設定を行う場合は、こちらを使用してください。 以下のコマンドではバージョン 0.3.9 を明示的に指定しているため、クライアントの再起動時にサーバーが予期せずアップグレードされることはありません。このバージョンがまだ公開されていない場合は、以下のソースからのインストールを使用してください。npm では、コンパイル済みの JavaScript と固定された実行時依存関係がインストールされます。ローカルでのビルドは不要です。

npx --yes [email protected] --version

設定は npm のインストール先や npx のキャッシュの外に置いてください。プライベートファイルを作成します。

mkdir -p "$HOME/.config/overleaf-mcp"
touch "$HOME/.config/overleaf-mcp/env"
chmod 600 "$HOME/.config/overleaf-mcp/env"

そのファイルをローカルで編集し、トークンとプロジェクト ID を記入します。

OVERLEAF_GIT_TOKEN=olp_your_token_here
OVERLEAF_PROJECTS=paper=64a1b2c3d4e5f6a7b8c9d0e1

mcpServers JSON 形式を使用するクライアントの場合：

{
  "mcpServers": {
    "overleaf": {
      "command": "npx",
      "args": ["--yes", "[email protected]", "--stdio"],
      "env": {
        "OVERLEAF_MCP_ENV_FILE": "/absolute/path/to/.config/overleaf-mcp/env"
      }
    }
  }
}

ファイルパスを実際の絶対パスに置き換えてください。JSON では ~ や $HOME は展開されません。 別の設定形式を使用するクライアントでは、同じ環境変数を設定して、同じコマンドと引数を実行してください。デスクトップアプリが npx を見つけられない場合は、command -v npx で確認できる絶対パスを使用してください。ソースからのインストール例と、クライアントごとの設定ファイルの場所については、クライアントガイドを参照してください。

または、クライアントの env で OVERLEAF_GIT_TOKEN と OVERLEAF_PROJECTS の両方を設定してください。OVERLEAF_MCP_ENV_FILE を指定した場合、環境変数はファイル内の個々の値より優先されます。明示的に指定したファイルパスが読み取れない場合、または相対パスの場合はエラーになります。指定しない場合、クライアントからプロジェクト設定または認証情報設定（ファイルパスを含む）が渡されないときに限り、インストール先の .env が使用されます。JSON 形式のプロジェクトファイルには、それぞれ異なる認証情報を設定できます。詳しくは設定ガイドを参照してください。 設定ファイルの検索で現在の作業ディレクトリが参照されることはありません。

クライアントを再起動した後、list_projects を呼び出して設定を確認し、list_files を呼び出して実際のプロジェクトへのアクセスを検証してください。ツールを検出できただけでは、Overleaf にアクセスできることの証明にはなりません。

ソースのチェックアウトからインストール

ステップ 1：ビルド

npm ci && npm run build

続行する前に、dist/index.js が存在することを確認してください。リポジトリのルートディレクトリの絶対パスを控えてください。以下の各クライアント設定で必要になります。クライアントは任意の作業ディレクトリからサーバーを起動するため、相対パスは機能しません。

ステップ 2：ユーザーから 2 つの値を取得

Git 認証トークン。 https://www.overleaf.com/user/settings の「Git integration」で生成します。1 つのトークンでそのユーザーのすべてのプロジェクトにアクセスでき、有効期限は 1 年です。トークンは olp_ で始まります。

ユーザーには、ステップ 3 のコマンドを使って、チャットではなく自分で .env に貼り付けるよう依頼してください。会話に貼り付けたトークンは、会話履歴に永久に残るため、ローテーションが必要です。それでも貼り付けた場合は、ローテーションするよう明確に伝えてから、作業を続けてください。

1 つ以上のプロジェクト ID。 プロジェクト URL の最後のパス要素です： https://www.overleaf.com/project/<projectId>。プロジェクト ID は、16 進数 24 文字ちょうどです。それ以外の値はプロジェクト ID ではないため、推測せずにもう一度確認してください。

ステップ 3：.env を作成し、トークンが機能することを確認

cp .env.example .env && chmod 600 .env

次に、ユーザーに以下を記入してもらいます：

OVERLEAF_GIT_TOKEN=olp_...
OVERLEAF_PROJECTS=paper=64a1b2c3d4e5f6a7b8c9d0e1

OVERLEAF_PROJECTS は、name=projectId のペアをカンマ区切りで並べたリストです。名前はユーザーが任意に付けるラベルです。名前のないプロジェクト ID のみも指定でき、その場合は ID 自体を名前として登録されます。登録するプロジェクトが 1 つだけの場合は、そのプロジェクトがデフォルトになります。複数ある場合は、OVERLEAF_DEFAULT_PROJECT を設定するか、default というエイリアスを使用するか、呼び出しごとにプロジェクト名を指定してください。

クライアントを設定する前に、認証情報を使って Overleaf に接続できることを確認します：

git ls-remote https://[email protected]/<projectId>

Git がパスワードの入力を求めます。ここに入力するのがトークンです。Refs が表示されれば動作しています。403 または Repository not found と表示される場合は、トークンが間違っているか、そのアカウントのプランに Git integration が含まれていません。すべてのツールがこれに依存しているため、先に問題を解決してください。

MCP クライアントはシェルを使わずにサーバーを起動するため、サーバーは .env を自ら読み込みます。これにより、ユーザーが権限を管理できる 1 つのファイルにトークンを保存でき、各クライアントの設定にコピーする必要がありません。クライアントが環境変数を明示的に設定した場合は、その値が優先されます。

ステップ 4：クライアントに登録する

ステップ 1 で取得した絶対パスを使用します。ユーザーが実際に指定したクライアントのみを設定してください。 クライアント固有の設定場所、確認方法、トラブルシューティングについては、 ローカル MCP クライアントガイドを参照してください。

Claude Code

claude mcp add overleaf -s user -- node /absolute/path/to/mcp-server-overleaf/dist/index.js --stdio

次に claude mcp list を実行し、✔ Connected と表示されることを確認してください。実際に確認するまでは、成功したと報告しないでください。

Claude Desktop または Cursor — クライアントの MCP 設定ファイルに追加します。ファイルの場所と再起動の手順はクライアントによって異なります。どちらもローカル MCP クライアントガイドに記載されています。

{
  "mcpServers": {
    "mcp-server-overleaf": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-overleaf/dist/index.js", "--stdio"]
    }
  }
}

Codex デスクトップ、CLI、または IDE 拡張機能 — 1 台の Codex ホスト上にあるクライアントは、~/.codex/config.toml を共有します。

[mcp_servers.mcp-server-overleaf]
command = "node"
args = ["/absolute/path/to/mcp-server-overleaf/dist/index.js", "--stdio"]

読み取りを自由に実行し、書き込みのたびに確認を求める場合は、サーバーテーブル内に default_tools_approval_mode = "writes" を追加します。

ChatGPT デスクトップのローカル MCP 設定では、このリポジトリがあるコンピューター上で同じ stdio コマンドを直接起動できます。このローカル設定は、同じホスト上の Codex クライアントと共有されます。UI と CLI の手順はローカル MCP クライアントガイドに記載されています。

ChatGPT Web またはワークスペース共有の ChatGPT アプリ — サーバーをパブリックインターネットに公開せずに、OpenAI Secure MCP Tunnel を使用します。ChatGPT は OpenAI ホストのトンネルエンドポイントに接続し、tunnel-client がリクエストを dist/index.js --stdio に転送します。 Secure MCP Tunnel の手順ガイドに従ってください。必要な Platform 組織と ChatGPT ワークスペースの関連付け、ランタイムキー、開発者モードでのアプリ設定、エンドツーエンドの確認について説明しています。

HTTP 経由のリモートクライアント

node dist/index.js --http --port 3017

--http は、OVERLEAF_MCP_HTTP_AUTH_TOKEN が設定されていないと起動を拒否します。トークンがない場合、ポートにアクセスできる人なら誰でもユーザーの論文を読み取り、書き換えられるためです。--allow-anonymous はこの制限を解除しますが、ポートがマシンの外部から本当にアクセスできない場合に限って使用してください。トークンがないことへの対処として使用しないでください。

ステップ 5：エンドツーエンドで確認する

list_files を呼び出します。ファイル一覧が表示されれば、設定、トークン、クローン、クライアント接続を含む一連の経路が機能しています。失敗した場合は、エラーメッセージに原因が示されます。

ツール

すべてのツールでは、省略可能な project を指定できます。これは、プロジェクトの Overleaf アドレス、生の 24 文字の ID、または OVERLEAF_PROJECTS に登録した名前です。省略すると、デフォルトが使用されます。すでに手元にある形式であるため、アドレスも受け付けます。まだ設定していない論文でも、アドレスを貼り付けてアクセスできます。未登録のプロジェクトにはデフォルトの Git トークンが必要です。登録済みのプロジェクトでは、それぞれに設定された認証情報が使用されます。

ツール	機能
list_projects	このサーバーがアクセスできるプロジェクトを一覧表示します
list_files	ファイルを種類ごとに一覧表示します。拡張子によるフィルターと、新しいローカルファイルの指定にも対応しています
read_file	テキストまたは行範囲を読み取ります。リビジョンを考慮した全件・変更なし・差分の読み取りにも対応しています
list_sections	.tex ファイル内のセクション区切りコマンドを、行範囲とともに一覧表示します
read_section	タイトルで検索したセクションの本文を読み取ります
search_project	追跡対象のテキストファイルを検索します
replace_text	曖昧な一致を拒否しながら、完全一致する箇所を置換します
edit_section	セクション全体を置き換えます
write_file	ファイルを上書きまたは作成します
delete_file	ファイルを削除します。プッシュするまではローカルの変更です
move_file	移動先を上書きせずに、ファイルを移動または名前変更します
show_diff	まだプッシュしていないすべての変更の差分を表示します
discard_local_changes	プッシュ前の編集とコミットを破棄し、Overleaf のバージョンに戻します
project_status	同期状態、保留中の編集、最近の履歴を表示します
project_summary	ファイル数、メインドキュメント、セクション、保留中の変更を JSON 形式で表示します
sync_project	Overleaf からプルします
compile_project	latexmk でコンパイルし、エラーを報告します
push_changes	コラボレーターを確認してから、コミットして公開します

ツールを安全に使う方法

編集内容は push_changes を実行するまでローカルにとどまります。これは設計全体に関わることであり、実装上の詳細ではありません。だからこそ、不適切な編集を公開せずに破棄できます。

push_changes を実行する前に show_diff を確認してください。実際のコミットメッセージを付けて、一度だけプッシュしてください。ユーザーには、Overleaf の履歴に共著者の記録と並んで表示されます。

push_changes は conflict-with-collaborator を返す場合があります。これは、作業中に誰かが同じ行を編集したことを意味します。何も公開されておらず、両方のバージョンがそのまま残っています。再試行したり、強制したり、自分でマージしようとしたりしないでください。競合を報告し、ユーザーの判断に任せてください。

プッシュが拒否されると、コミットはクローンに残ります。その結果、クローンは Overleaf より進んでいると同時に遅れている状態になり、その後の同期はすべて同じ行で競合します。解決するには discard_local_changes を使います。これにより、プッシュしていないコミットだけでなく、コミット前の編集も破棄され、クローンは Overleaf にある状態に戻ります。破棄されるのはユーザーの編集内容です。実行する前に、何が破棄されるのかをユーザーに伝えてください。

replace_text は、対象のスニペットが複数回出現すると、最初のものだけを黙って変更せず、処理を拒否します。前後の文脈を加えて一意にするか、意図的に replaceAll を指定してください。

write_file よりも replace_text と edit_section を優先してください。write_file はファイル全体を置き換えるため、文書を部分的に再構成すると、残りの内容が黙って削除されます。

delete_file と move_file は、ほかの編集と同様に push_changes を実行するまでローカルにとどまるため、プッシュする直前まで discard_local_changes で取り消せます。どちらも LaTeX の参照を書き換えません。移動した後は、search_project で古いパスを検索し、まだそのパスを指定している \input、\include、\includegraphics を修正してください。そうしないと、論文をコンパイルできなくなります。削除する前に、そのファイルが本当に使われていないことを確認してください。共著者の \input が1つあるだけでも、相手のビルドが失敗します。

読み取りと編集を行う場合は、mode: "full" または "smart" を指定して read_file を呼び出し、その revision を編集ツールの expectedRevision に渡してください。これにより、読み取り後に共著者または別のクライアントがファイルを変更していた場合、編集は上書きを拒否します。リビジョンプロトコルを参照してください。

コンパイルは任意であり、必須の条件ではありません。push_changes は文書がビルドできるか確認しないため、事前に確認しなければ、壊れた文書が公開されることがあります。

設定リファレンス

変数	意味
OVERLEAF_GIT_TOKEN	デフォルトの認証情報です。トークンファイルまたはプロジェクトごとの認証情報が指定されていない場合は必須です。
OVERLEAF_GIT_TOKEN_FILE	デフォルトのトークンファイルへの絶対パスです。
OVERLEAF_PROJECTS_CONFIG	プロジェクトごとに独立した認証情報を含む JSON プロジェクトファイルへの絶対パスです。
OVERLEAF_PROJECT_ID / OVERLEAF_PROJECT_NAME	OVERLEAF_PROJECTS の代わりに使える単一プロジェクト向けの設定です。
OVERLEAF_MCP_ENV_FILE	外部設定ファイルへの絶対パスです。npm/npx での使用に推奨されます。
OVERLEAF_PROJECTS	name=projectId のペアです。JSON または生の ID でアクセスする場合は省略できます。
OVERLEAF_DEFAULT_PROJECT	呼び出し時に project が省略された場合に使用する、登録済みの名前です。
OVERLEAF_MCP_CHECKOUT_MODE	full（デフォルト）または text-only です。展開動作については設定ガイドを参照してください。
OVERLEAF_MCP_WORKSPACE_DIR	クローンを保存する場所です。デフォルトは ~/.overleaf-mcp/projects です。
OVERLEAF_GIT_BASE_URL	デフォルトは https://git.overleaf.com です。
OVERLEAF_MCP_COMPILE_TIMEOUT_MS	コンパイルのタイムアウトです。正の整数を指定する必要があります。
OVERLEAF_MCP_HTTP_AUTH_TOKEN	--http に必要なベアラートークンです。
OVERLEAF_MCP_HTTP_PORT	--http 用のポートです。--port を指定すると、こちらが優先されます。
OVERLEAF_SESSION_COOKIE	Overleaf のセッションクッキーです。有効にすると、3つの変更履歴ツールが使えるようになります。
OVERLEAF_SESSION_COOKIE_FILE	同じ値を含むファイルへの絶対パスです。環境変数より優先されます。
OVERLEAF_WEB_BASE_URL	これらのツールで使用する Overleaf のウェブアドレスです。デフォルトは https://www.overleaf.com です。

想定どおりの動作をする理由

Overleaf の git ブリッジは、汎用の git リモートではありません。各プロジェクトにはブランチが正確に 1 つあり、履歴は直線的です。強制プッシュは拒否され、タグ、サブモジュール、LFS はありません。ここでのすべての動作は、この範囲内に収まります。

本当のリスクはプッシュの失敗ではなく、共著者の変更を気付かないまま上書きすることです。そのため、編集と公開は別々に行います。

1. 読み取りと編集のたびに、まず Overleaf と同期します。ローカルの作業が同期を妨げる場合、呼び出しは失敗し、その作業は保持されます。show_diff で確認してから、公開するか、明示的に破棄してから続行してください。古い状態での読み取りと編集は拒否されます。
2. 編集内容はローカルクローンにのみ反映されます。push_changes を実行するまで、Overleaf には反映されません。
3. push_changes はプッシュの直前に Overleaf を再確認し、その間に反映された変更の上にリベースします。クリーンに適用できない場合、推測で解決するのではなく、プッシュを拒否して競合を報告します。

Git の認証情報は認証ヘルパーを通じて git に渡されるため、認証トークンが argv や .git/config に含まれることはありません。Git の診断では選択された認証情報が伏せられ、ツールのエラーでは設定済みのすべてのプロジェクト認証情報が伏せられます。接続済みのクライアントから意図的に読み取り可能なプロジェクトファイルには、シークレットを含めないでください。

コンパイルはクローンの外部に書き込まれるため、.aux、.log、.pdf ファイルがステージングされ、プッシュされることはありません。また、クローンにはローカルの除外リストが適用されるため、.DS_Store が共著者のプロジェクトに届くことはありません。

ツールの呼び出しはプロジェクトごとに直列化されます。まずプロセス内キューで直列化され、次にワークスペース内のロックディレクトリで直列化されます。そのため、同じサーバーを 2 つのクライアントに登録した場合など、2 つ目のサーバープロセスは競合する代わりに待機します。

クライアントから渡されたパスは 2 回検査されます。1 回目はパスとして、2 回目はシンボリックリンクを解決した後のファイルシステム上で検査します。これにより、クローン内のリンクから外部や .git にアクセスすることはできません。

レイアウト

src/
  config/      environment parsing, secret redaction
  overleaf/    git command runner, repository operations, project registry, path safety
  latex/       section parsing, file categorization
  workflow/    sync-before-edit, publish-with-conflict-check, compile
  tools/       MCP tool definitions
  transport/   stdio and Streamable HTTP
  server/      server factory shared by both transports
tests/
  config/ latex/ overleaf/  unit tests, run in-process
  features/                 Gherkin specifications, bound to the server over stdio
  integration/              spawn the built server and speak MCP to it over stdio or HTTP

開発

npm run check

型チェッカー、Biome、ビルド、テストをまとめて実行します。 型チェッカーの対象にはテストコードも含まれます。Vitest を実行するたびに、対象を絞った実行やカバレッジ実行を含め、必ずサーバーを先にビルドします。そのため、サブプロセステストで古い dist が使われることはありません。

コマンド	内容
npm run typecheck	ソース、テスト、Vitest の設定を型チェックします
npm run lint	Biome による lint とフォーマットのチェック
npm run format	Biome で修正を適用します
npm test	ビルド後、Vitest でテストスイート全体を実行します
npm run package:check	2 回ビルドして tarball を比較し、ユーザーと同じ方法でインストールして、インストール済みサーバーをテストします
npm run check:release	ソースのチェック、パッケージのチェック、依存関係の監査を実行します
npm run test:coverage	ビルド後、v8 カバレッジ付きで Vitest を実行します

テストスイートでは、スキーマ、エラーフラグ、読み取り、編集、確認、公開など、同じツールの契約を stdio と HTTP の両方で検証します。復旧テストでは、ダーティーツリーの同期、競合からの復旧、リモートによる拒否と再接続、プロセスの再起動、ロック保持プロセスの強制終了、同時接続クライアントを検証します。新しいファイルと未プッシュのコミットは、show_diff で引き続き確認できる必要があります。決定的なサブプロセス用フィクスチャにより、ネットワーク接続や TeX のインストールなしで、Git とコンパイラーのタイムアウトをテストできます。

tests/features/ では、Gherkin のフィーチャーファイルを使って公開の契約を記述します。共著者に見える内容を平易な文で記述し、それぞれの文を stdio 経由でサーバーに対して行う実際の呼び出しに結び付けます。バインディングのない文があると実行は失敗するため、説明する動作とドキュメントが乖離することはありません。シナリオを追加するには、.feature ファイルに記述し、その隣の .test.ts ファイルで新しいステップをバインドします。ステップはフィーチャー内のシナリオ間で共有されるため、新しいシナリオの多くはバインディングを追加する必要がありません。 TeX に依存するテストは、共通の可用性チェックを使用します。TeX を使わずに実行するには OVERLEAF_TEST_TEX=skip を設定し、latexmk または pdflatex が見つからない場合に失敗させるには OVERLEAF_TEST_TEX=required を設定します。デフォルトの auto では、両方の実行ファイルが利用可能な場合にテストを実行します。GitHub Actions では、Node 22.14、24、26 を使った Linux と macOS でのコアチェックに加え、TeX をインストールしてコンパイルテストの実行を必須とする Linux ジョブも実行します。

npm-shrinkwrap.json が正式な依存関係ロックファイルです。npm で更新し、package.json と一緒にコミットしてください。公開パッケージに含まれるコピーは、このファイルのランタイム用の部分です。 prepack で開発用の項目を削除し、postpack で完全なロックファイルに戻します。npm は同梱されたロックファイルをもとに依存関係のツリーを構築するため、こうしないと、すべてのユーザーの環境にコンパイラー、リンター、テストランナーがインストールされてしまいます。パッケージチェックでは、tarball 内の shrinkwrap に開発用の依存関係が残っていると失敗します。 リリース用パッケージテストでは、無関係な作業ディレクトリにインストールした tarball に対して統合テストスイートを再利用し、stdio、HTTP、編集、競合、復旧を検証します。

このインストールでは、アーカイブ内の shrinkwrap ではなくレジストリを参照して、宣言された範囲に合致する依存関係を新たに解決します。そのため、テスト対象のツリーは、それらの範囲で許可される最新のものであり、バージョンではなく構成に基づいてロックファイルと比較されます。一方のツリーにしか存在しないパッケージがあればチェックは失敗します。また、メジャーバージョンに差がある場合（0.x パッケージではマイナーバージョンに差がある場合）も失敗します。直接の依存関係に変更がなくても、バージョンが固定されていないピア依存関係によって差が生じることがあります。新しいパッチまたはマイナーバージョンは表示するだけで、npm update を実行するとロックファイルを最新の状態にできます。両方のツリーでテストを実行します。バージョンの一致まで必須にすると、依存関係に手を加えていないブランチで、上流のパッチリリースが出るたびにテストが失敗していました。

テストで実際の Overleaf に接続することはありません。tests/integration/fakeOverleafRemote.ts は、ベアの git リポジトリと、共著者役の 2 つ目のクローンを用意し、安全性の契約が前提とするすべての動作、つまり fetch、rebase、拒否される push を再現します。

カバレッジは実際より低く表示されます。統合テストは別プロセスとして node dist/index.js を起動しますが、v8 は子プロセスを計測できません。そのため、実際の MCP ワイヤープロトコルを介してエンドツーエンドで動作をテストしているにもかかわらず、src/tools/ と src/server/ のカバレッジは 0% と報告されます。

よくある質問

Claude Code または Claude Desktop で Overleaf プロジェクトを編集できますか？

はい。Claude Desktop ではワンクリックの .mcpb バンドルをインストールでき、Claude Code ではリポジトリをプラグインとしてインストールするか、stdio 経由で npm パッケージを実行できます。どちらでも、安全な読み取り、編集、コンパイル、差分確認、push の同じワークフローを利用できます。

Codex、ChatGPT、Cursor、または VS Code から Overleaf に接続できますか？

はい。Codex では同梱のプラグインをインストールでき、Cursor やその他のローカルクライアントでは npm パッケージを実行できます。VS Code では .vscode/mcp.json を使用でき、ChatGPT では外向き接続のみの Secure MCP Tunnel を介して接続できます。最短の方法はクライアントの表をご覧ください。

AI による編集で共著者の作業が上書きされますか？

黙って上書きされることはありません。サーバーは読み取りと書き込みの前に同期し、明示的に push_changes を実行するまで編集をローカルに保持します。また、公開の直前に Overleaf を再確認します。共著者が同じ行を変更していた場合、push は拒否され、両方のバージョンが保持されます。

無料の Overleaf アカウントでも使えますか？

Git を使用する 16 個のツールには、プロジェクトで Git 統合が有効になっている必要があります。Overleaf では、この機能はプロジェクト所有者の対象サブスクリプションに応じて利用できます。そのため、招待された無料アカウントでも、プロジェクト所有者が個人、グループ、または機関向けプランを通じてアクセス権を持っていれば利用できます。

LaTeX のコンパイルや変更履歴の表示はできますか？

はい。latexmk と TeX ディストリビューションがインストールされている場合、compile_project はローカルで実行されます。オプションで Overleaf セッション Cookie を指定すると、追加の 3 つのレビュー用ツールで、変更履歴付きの提案の作成、変更履歴とコメントの一覧表示、選択したテキストへのコメントができます。

プライバシーポリシー

このサーバーはすべてお使いのコンピューター上で実行されます。分析機能もテレメトリーもなく、背後で動作するサービスもありません。外部への通信は、Overleaf への HTTPS 経由の Git 通信のみです。トークンは、Claude Desktop がバンドルをインストールする際にはオペレーティングシステムのキーチェーンに、それ以外の場合は setup が書き込むモード 600 のファイルに保存され、エラー出力では伏せられます。

ツールが返す内容はすべて、接続した MCP クライアントとの会話の一部となり、そのクライアント独自のポリシーに従って処理されます。

全文：docs/privacy-policy.md。

ライセンス

MIT