codex-mcp

English README: README.en.md

短いセットアップガイド: SETUP.md

Claude CodeからOpenAI Codexを、読み取り専用の設計・深い推論・コードレビュー役として呼び出すプラグインです。fable-mcpと逆向きの構成です。

ユーザー
  ↓
Claude Code（実装担当）
  ↓ MCP
codex-mcp
  ↓ Codex CLI
GPT-5.6 Solなど（設計・推論・レビュー担当）

一文でセットアップ

最も簡単な方法は、次の一文をClaude Codeまたは普段使っているコーディングエージェントへ渡すことです。

https://github.com/sam-mountainman/codex-mcp をセットアップして。

受け取ったエージェントはAGENTS.mdをセットアップ契約として読み、Node.js、Codex CLI、Claude Code、認証、プラグイン登録、実動確認まで進めます。APIキーを通常チャットへ貼る必要はありません。

機能

• gpt_plan: リポジトリを読んで具体的な実装計画を作る
• gpt_ask: 技術相談、難しいデバッグ、トレードオフ分析
• gpt_review: 現在の差分を読み取り専用でレビューする
• gpt_continue: session_idを使って同じCodex会話を継続する
• gpt_status: CLI、認証、モデル一覧、既定値をローカル診断する（モデル利用なし）

既定値はgpt-5.6-solとmaxです。すべてのモデル呼び出しはapproval_policy=never、sandbox_mode=read-onlyで実行されるため、Codex側はリポジトリを変更できません。

セットアップ

前提はNode.js 18以上です。セットアップスクリプトは、Codex CLIまたはClaude Codeがなければ公式npmパッケージをインストールし、MCPをビルドしてClaude Codeへプラグイン登録します。

macOS / Linux:

git clone https://github.com/sam-mountainman/codex-mcp.git
cd codex-mcp
./install.sh

Windows PowerShell:

git clone https://github.com/sam-mountainman/codex-mcp.git
Set-Location codex-mcp
.\install.ps1

既にCodexへログイン済みなら、その認証を再利用します。未ログイン時はChatGPTログイン（推奨）またはAPIキーを選べます。

明示指定する場合:

# ChatGPTアカウントでログイン
./install.sh --auth=chatgpt

# 環境変数のAPIキーでログイン（キーはコマンド引数に載せない）
OPENAI_API_KEY=... ./install.sh --auth=api

# プラグインだけセットアップ
./install.sh --auth=skip --skip-live-check

完了後にClaude Codeを再起動するか/reload-pluginsを実行し、Codexの状態を確認してと依頼してください。

モデル・推論レベルの変更

Claude Codeへ自然文で指定できます。

GPT-5.6 Terra、reasoning lowでこの設計を考えて
Solのmaxで実装をレビューして
さっきのsession_idをLunaのmediumで続けて

MCPツールを直接呼ぶ場合の例:

{
  "task": "この機能の設計と実装計画を作って",
  "model": "gpt-5.6-sol",
  "reasoning_effort": "max",
  "cwd": "/absolute/path/to/project"
}

サーバーが受け付ける推論値はnone / low / medium / high / xhigh / max / ultraです。実際に使える組み合わせはローカルCodex CLIのモデルカタログに従います。gpt_statusで対象モデルの対応値を確認できます。

環境変数でサーバー既定値も変更できます。

export CODEX_MCP_DEFAULT_MODEL=gpt-5.6-terra
export CODEX_MCP_DEFAULT_REASONING_EFFORT=medium

その他の設定:

• CODEX_MCP_CODEX_BIN: Codex CLIの絶対パス
• CODEX_MCP_TIMEOUT_MS: 1回のタイムアウト（既定20分）
• CODEX_MCP_MAX_OUTPUT_CHARS: MCPへ返す最大文字数（既定200,000）

開発・検証

npm install
npm run verify
npm run live-smoke
claude plugin validate --strict .

npm run live-smokeだけが実際にモデルを呼び出します。その他のテストはローカルのみです。

ローカル開発中はマーケットプレイスへ登録せず、Claude Codeを次のように起動して確認することもできます。

claude --plugin-dir /absolute/path/to/codex-mcp

認証と課金

内部ではResponses APIを直接呼ばず、codex exec --jsonを使います。そのためCodex CLIが公式に対応する両方の認証を利用できます。

• ChatGPTログイン: ChatGPTプラン側のCodex利用枠
• OpenAI APIキー: OpenAI Platformの従量課金

APIキーやCodexの認証ファイルをリポジトリへ保存しません。APIキー方式のセットアップでも、キーは環境変数から標準入力へ渡し、コマンド引数や通常出力には載せません。

制約

• modelは将来のCodexモデルIDも通せるよう固定リストにしていません。最終的な有効性はCodex CLIが検証します。
• reasoning_effortはCLI/APIで差があり得ます。例えばローカルカタログがnoneを表示しないモデルでは、その値は実行時に拒否される場合があります。
• gpt_continueはCodex CLIが保存したセッションを使うため、初回呼び出しと同じローカル認証・Codexホームが必要です。

ライセンス

MIT

参考資料

• OpenAI: GPT-5.6モデルガイド
• OpenAI: Codex認証
• OpenAI: Codex非対話モード
• Anthropic: Claude Codeプラグイン
• Anthropic: Claude CodeでMCPを使う
• 参照実装: fable-mcp