Codex Mcp Server

Codex MCP サーバー

Claude／Cursor と Codex CLI を接続する MCP サーバーです。@ によるファイル参照、複数ターンの会話、サンドボックス内での編集、構造化された変更モードを使ったコード分析を実現します。

機能

• ファイル分析 — @src/、@package.json の構文でファイルを参照します
• 複数ターンのセッション — ワークスペースを分離しながら会話を継続します
• ネイティブ再開 — codex resume を使用してコンテキストを保持します（CLI v0.36.0+）
• ローカル OSS モデル — localProvider を介して Ollama または LM Studio で実行します
• ウェブ検索 — search: true でリサーチ機能を利用できます
• サンドボックスモード — 明示的なサンドボックスと承認ポリシーによる安全な自動化
• 変更モード — リファクタリング向けに、OLD／NEW 形式の構造化パッチを出力します
• ブレインストーミング — SCAMPER、デザイン思考、水平思考のフレームワーク
• ヘルス診断 — CLI のバージョン、機能、セッションを監視します
• クロスプラットフォーム — Windows、macOS、Linux を完全にサポート

クイックスタート

claude mcp add codex-cli -- npx -y @trishchuk/codex-mcp-tool

前提条件： Node.js 18+、インストール済みで認証済みの Codex CLI。

設定

{
  "mcpServers": {
    "codex-cli": {
      "command": "npx",
      "args": ["-y", "@trishchuk/codex-mcp-tool"]
    }
  }
}

設定ファイルの場所： macOS：~/Library/Application Support/Claude/claude_desktop_config.json | Windows：%APPDATA%\Claude\claude_desktop_config.json

使用例

// File analysis
'explain the architecture of @src/';
'analyze @package.json and list dependencies';

// With specific model
'use codex with model gpt-5.6-sol to analyze @algorithm.py';

// Multi-turn conversations (v1.4.0+)
'ask codex sessionId:"my-project" prompt:"explain @src/"';
'ask codex sessionId:"my-project" prompt:"now add error handling"';

// Brainstorming
'brainstorm ways to optimize CI/CD using SCAMPER method';

// Sandbox mode
'use codex sandbox:true to create and run a Python script';

// Web search
'ask codex search:true prompt:"latest TypeScript 5.7 features"';

// Local OSS model (Ollama)
'ask codex localProvider:"ollama" model:"qwen3:8b" prompt:"explain @src/"';

ツール

ツール	説明
ask-codex	ファイル、モデル、セッション、安全制御を指定して Codex CLI を実行します
batch-codex	複数のアトミックな Codex タスクを順次または同時に実行します
review-changes	ネイティブの非対話型 Codex レビューコマンドを実行します
do-act	実行し、シェルコマンドで検証して、修正を再試行します
image-gen	Codex 内蔵の image_gen ツールで画像を生成または編集します
brainstorm	構造化された創造的フレームワークでアイデアを生成します
list-sessions	MCP の会話マッピングを表示、削除、または消去します
list-skills	選択したワークスペースから参照できるスキルを一覧表示します
health	CLI のインストール、バージョン、機能、セッションを診断します
fetch-chunk	キャッシュされた変更モードの出力からチャンクを取得します
ping	MCP 接続をテストします
help	現在の codex --help の出力を返します
version	Codex CLI、Node.js、プラットフォーム、パッケージのバージョンを報告します
timeout-test	キープアライブとタイムアウトの動作をテストします

画像生成

image-gen は Codex に組み込まれた image_gen ツールを使用するため、ChatGPT のログインを使い、OPENAI_API_KEY は不要です。このツールが受け付けるのはプロンプトと参照画像のパスのみです。画像モデルとピクセルサイズは Codex が選択し、サイズ、品質、形式、マスクの引数はありません。そのため image-gen は、構造化されたプロンプト（用途、アセットの種類、スタイル、構図、正確なテキスト、参照画像の役割、編集時に維持する要素、アスペクト比、プリセット）にすべての指示を盛り込み、Codex のホストモデルに独自の判断を加えずそのまま伝えるよう指示します。

// New image, 16:9, exact Cyrillic headline, copied into the project
'image-gen prompt:"YouTube cover about AI coding agents" aspect:"wide" text:"АГЕНТИ БЕЗ ХАОСУ" presets:["thumbnail","exact-text"] outputPath:"assets/cover.png"';

// Edit: change only the headline, keep everything else
'image-gen editImage:"assets/cover.png" prompt:"Replace the headline text" text:"ЧАСТИНА 2" preserve:["people and background"] outputPath:"assets/cover.png"';

画像は Codex によって $CODEX_HOME/generated_images/<thread>/ に保存され、指定された場合は outputPath にコピーされます。ファイルがすでに存在する場合はそのまま残され、コピーは -v2 を付けた別ファイルとして書き込まれます。ただし、overwrite: true の場合は上書きされます。結果には各ファイルの寸法とアルファチャンネルが報告されるため、transparentBackground を指定したのに不透明な画像が返された場合は、そのことが示されます。

モデル

デフォルトでは model パラメーターは省略され、Codex CLI が ~/.codex/config.toml に設定されたデフォルトモデル（例：model = "gpt-6.1-sol"）を適用します。設定済みのデフォルトを単一の呼び出しで上書きする必要がある場合にのみ、model を渡してください。推論の深さはツールごとに調整されています。

• ask-codex — Codex CLI のデフォルトの推論（medium）を使用します。タスクに追加の計画や確認が必要な場合にのみ、推論の深さを上げてください。
• brainstorm、do-act、review-changes — デフォルトは reasoningEffort: "high" です（創造的なアイデア出し、実行・確認・修正の反復、コードレビューでは、より深い推論が役立ちます）。

モデル	推奨用途
gpt-6.1-sol	コーディングや日常的な作業に最適な最新の主力モデル（CLI 0.159+）
gpt-6-astra	最も難しい作業向けの最先端の知能
gpt-6-sol	前世代の主力モデル
gpt-6-luna	高速で手頃な価格。簡単で繰り返し行うタスク向け
gpt-5.6-sol	旧世代の主力モデル
gpt-5.6-terra	定型的な作業向けの旧世代のバランス型モデル
gpt-5.6-luna	旧世代の高速で効率的なモデル
gpt-5.5	レガシー — Codex は呼び出し元に gpt-5.6-sol を案内します

Sol、Astra、Terra モデルでは max と ultra の推論レベルを利用できます。Luna モデルの上限は max、gpt-5.5 の上限は xhigh です。ultra ではサブエージェントに作業を委任する場合があります。ほとんどのタスクでは medium または high を使用してください。具体的なスラッグを渡してください。gpt-6 と gpt-5.6 という移動エイリアスのみの指定は、API で拒否されます。Codex CLI 0.157.x では gpt-6.1-sol は未知のスラッグと同じ 400 エラーで拒否されるため、npm install -g @openai/codex@latest でアップグレードしてください。

主な機能

セッション管理（v1.4.0+）

ワークスペースを分離したマルチターンの会話：

{ "prompt": "analyze code", "sessionId": "my-session" }
{ "prompt": "continue from here", "sessionId": "my-session" }
{ "prompt": "start fresh", "sessionId": "my-session", "resetSession": true }

環境変数：

• CODEX_SESSION_TTL_MS - セッションの TTL（デフォルト：24h）
• CODEX_MAX_SESSIONS - セッションの最大数（デフォルト：50）

Codex CLI のバージョン

Codex CLI 0.95.0 以降が必要です。古いバージョンでは、未対応のフラグを黙って無視するのではなく、明示的なアップグレードメッセージを表示してサーバーが失敗します。npm install -g @openai/codex@latest でアップグレードし、health ツールを実行して検出されたバージョンを確認してください。

トラブルシューティング：「codex が見つかりません」

GUI（Dock、Finder、スタートメニュー）から起動した MCP クライアントでは、最小限の PATH が引き継がれ、Homebrew、nvm、volta のディレクトリが含まれないことがあります。そのため、ターミナルでは codex が動作しても、アプリでは動作しない場合があります。サーバーはこれらの場所を自動的に検索します。それでも CLI が見つからない場合は、明示的に指定してください。

{ "env": { "CODEX_CLI_PATH": "/opt/homebrew/bin/codex" } }

which codex で値を確認してください。health ツールを実行すると、解決された実行ファイルとその方法を確認できます。

ローカル OSS モデル（v1.6.0+）

OpenAI の代わりに、ローカルの Ollama または LM Studio を使って実行します。

// Ollama
{ "prompt": "analyze @src/", "localProvider": "ollama", "model": "qwen3:8b" }

// LM Studio
{ "prompt": "analyze @src/", "localProvider": "lmstudio", "model": "my-model" }

// Auto-select provider
{ "prompt": "analyze @src/", "oss": true }

要件： ツール呼び出しに対応するモデル（例：qwen3:8b）を備えた Ollama がローカルで実行されていること。

高度なオプション

パラメーター	説明
model	モデルの選択
sessionId	会話の継続性を有効にする
sandbox	互換性のための自動化：workspace-write + never
search	ウェブ検索を有効にする
changeMode	構造化された OLD/NEW の編集
addDirs	書き込み可能なディレクトリの追加
toolOutputTokenLimit	応答の冗長さを制限（100-10,000）
reasoningEffort	low、medium、high、xhigh、max、ultra
oss	ローカルの OSS モデルプロバイダーを使用する
localProvider	ローカルプロバイダー：lmstudio または ollama
strictConfig	不明な Codex 設定キーがある場合に失敗する
ephemeral	Codex セッションファイルを永続化しない
ignoreUserConfig	$CODEX_HOME/config.toml を無視する
ignoreRules	execpolicy の .rules ファイルを無視する

CLI の互換性

Codex CLI 0.144.3 に対して検証済みです。サーバーには古い機能のガードが残っていますが、現行リリースの使用を推奨します。現在の動作に関する注意点：

• --full-auto と承認ポリシー on-failure は Codex CLI から削除されています。
• MCP の sandbox: true / fullAuto: true は、引き続き --sandbox workspace-write --ask-for-approval never の互換性エイリアスとして機能します。サンドボックスを回避するものではありません。
• 非推奨の web_search_request 機能を使わず、ネイティブの --search を使用します。
• 現行の exec フラグには --strict-config、--ephemeral、 --ignore-user-config、--ignore-rules が含まれます。

トラブルシューティング

codex --version    # Check CLI version
codex login        # Authenticate

診断には health ツールを使用してください：'use health verbose:true'

移行

v2.5.x → v2.6.0： Codex CLI 0.159.2 のモデル同期と、新しい image-gen ツール。 gpt-6.1-sol（Codex CLI 0.159 以降が必要）、gpt-6-sol、gpt-6-luna を追加しました。 破壊的変更： gpt-5.4-mini を削除しました。このモデルは HTTP 400 を返すようになりました。

v2.4.x → v2.5.0： Codex CLI 0.153.4 との互換性対応を実施し、 gpt-6-astra を追加しました。破壊的変更： gpt-5.4 と、変動するエイリアス gpt-5.6 （どちらも HTTP 400 で拒否されるようになりました）を削除し、Codex CLI 0.153.x で解析できなくなった承認ポリシー untrusted も削除しました。

v2.3.x → v2.4.0： Codex CLI 0.144.3 との互換性を監査し、GPT-5.6 Sol/Terra/Luna、max/ultra の推論、現行の exec フラグ、ネイティブ検索のみの使用、 削除された --full-auto フラグと承認ポリシー on-failure への安全な互換対応を追加しました。

v2.2.x → v2.3.0： gpt-5.5 を新しいデフォルトに設定し、gpt-5.4-mini を追加、廃止されたモデル（gpt-5.3-codex-spark、gpt-5.2-codex、gpt-5.1-codex-max、gpt-5.1-codex-mini）を削除しました。

v2.0.x → v2.1.0： gpt-5.4 を新しいデフォルトモデルに設定し、フォールバックチェーンを更新しました。

v1.5.x → v1.6.0： ローカル OSS モデルのサポート（localProvider、oss）、gpt-5.3-codex のデフォルトモデル設定、xhigh の推論強度を追加しました。

v1.3.x → v1.4.0： 新しい sessionId パラメーター、list-sessions/health ツール、構造化されたエラー処理を追加しました。破壊的変更はありません。

ライセンス

MIT ライセンス。OpenAI とは提携していません。

---

ドキュメント | 問題の報告 | jamubc/gemini-mcp-tool に着想を得ています