Codex MCP Server

🚀 Codex MCP Tool

Codex MCP Toolは、オープンソースのModel Context Protocol (MCP)サーバーです。これにより、IDEやAIアシスタント（Claude、Cursorなど）をCodex CLIに接続できます。codex execを使用した非対話型自動化、承認付きの安全なサンドボックス編集、@ファイル参照による大規模なコード分析を可能にします。信頼性と速度を重視して構築され、進行状況の更新をストリーミングし、構造化された変更モード（OLD/NEWパッチ出力）をサポートし、コードレビュー、リファクタリング、ドキュメント作成、CI自動化などの標準的なMCPクライアントとシームレスに統合されます。

最新リリース (v1.2.4): Windows互換性の強化 - すべてのプラットフォーム（Windows、macOS、Linux）で信頼性の高いnpmグローバルコマンド実行のために、cross-spawnを使用するようになりました。変更履歴を参照

🚀 クイックスタート

目標

MCP対応のエディタから直接Codexを使用して、コードを効率的に分析および編集することです。

前提条件

このツールを使用する前に、以下が必要です。

1. Node.js (v18.0.0以上)
2. Codex CLI がインストールされ、認証されていること

✅ クロスプラットフォームサポート: Windows、macOS、Linuxで完全にテストされ、動作しています (v1.2.4+)

ワンラインセットアップ

claude mcp add codex-cli -- npx -y @cexll/codex-mcp-server

インストールの確認

Claude Code内で/mcpと入力して、Codex MCPがアクティブであることを確認します。

代替方法: Claude Desktopからのインポート

もしClaude Desktopですでに設定されている場合は、以下の手順を実行します。

1. Claude Desktopの設定に追加します。

"codex-cli": {
  "command": "npx",
  "args": ["-y", "@cexll/codex-mcp-server"]
}

2. Claude Codeにインポートします。

claude mcp add-from-claude-desktop

📦 インストール

設定

MCPサーバーをMCPクライアントに登録します。

NPXを使用する場合 (推奨)

Claude Desktopの設定ファイルに以下の設定を追加します。

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

グローバルインストールの場合

グローバルにインストールした場合は、代わりに以下の設定を使用します。

{
  "mcpServers": {
    "codex-cli": {
      "command": "codex-mcp"
    }
  }
}

設定ファイルの場所:

• Claude Desktop:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/claude/claude_desktop_config.json

設定を更新した後、ターミナルセッションを再起動します。

💻 使用例

モデル選択

// デフォルトのgpt-5-codexモデルを使用
'explain the architecture of @src/';

// 高速な汎用推論にgpt-5を使用
'use codex with model gpt-5 to analyze @config.json';

// 深い推論タスクにo3を使用
'use codex with model o3 to analyze complex algorithm in @algorithm.py';

// 高速なタスクにo4-miniを使用
'use codex with model o4-mini to add comments to @utils.js';

// ソフトウェアエンジニアリングにcodex-1を使用
'use codex with model codex-1 to refactor @legacy-code.js';

ファイル参照を使用する場合 (@構文)

• ask codex to analyze @src/main.ts and explain what it does
• use codex to summarize @. the current directory
• analyze @package.json and list dependencies

一般的な質問 (ファイルなし)

• ask codex to explain div centering
• ask codex about best practices for React development related to @src/components/Button.tsx

アイデア出しと構想立案

• brainstorm ways to optimize our CI/CD pipeline using SCAMPER method
• use codex to brainstorm 10 innovative features for our app with feasibility analysis
• ask codex to generate product ideas for the healthcare domain with design-thinking approach

Codexの承認とサンドボックス

Codex CLIは、サンドボックスモードと承認ポリシーを通じて、権限と承認の細かい制御をサポートしています。

パラメータの理解

sandboxパラメータ (便利なフラグ):

• sandbox: true → fullAutoモードを有効にします (fullAuto: trueと同等)
• sandbox: false (デフォルト) → サンドボックス化を無効にするわけではなく、自動モードを有効にしないだけです
• 重要: sandboxパラメータは便利なフラグであり、セキュリティ制御ではありません

細かい制御パラメータ:

• sandboxMode: ファイルシステムアクセスレベルを制御します
• approvalPolicy: ユーザーの承認が必要なタイミングを制御します
• fullAuto: sandboxMode: "workspace-write" + approvalPolicy: "on-failure"の省略形です
• yolo: ⚠️ すべての安全チェックをバイパスします (危険で、推奨されません)

サンドボックスモード

承認ポリシー

設定例

例1: バランスの取れた自動化 (推奨)

{
  "approvalPolicy": "on-failure",
  "sandboxMode": "workspace-write",  // v1.2+で省略された場合は自動設定
  "model": "gpt-5-codex",
  "prompt": "refactor @src/utils for better performance"
}

例2: クイック自動化 (便利モード)

{
  "sandbox": true,  // fullAuto: trueと同等
  "model": "gpt-5-codex",
  "prompt": "fix type errors in @src/"
}

例3: 読み取り専用分析

{
  "sandboxMode": "read-only",
  "model": "gpt-5-codex",
  "prompt": "analyze @src/ and explain the architecture"
}

スマートデフォルト (v1.2+)

バージョン1.2.0から、サーバーは権限エラーを防止するために自動的にスマートなデフォルトを適用します。

• ✅ approvalPolicyが設定されているが、sandboxModeが設定されていない場合 → sandboxMode: "workspace-write"を自動設定します
• ✅ search: trueまたはoss: trueの場合 → sandboxMode: "workspace-write"を自動設定します (ネットワークアクセス用)
• ✅ すべてのコマンドに--skip-git-repo-checkが含まれており、非git環境でのエラーを防止します

権限エラーのトラブルシューティング

❌ Permission Error: Operation blocked by sandbox policyというエラーが発生した場合は、以下を確認します。 チェック1: sandboxModeを確認する

# 書き込み操作に読み取り専用モードを使用していないことを確認
{
  "sandboxMode": "workspace-write",  // "read-only"ではない
  "approvalPolicy": "on-failure"
}

チェック2: 便利なフラグを使用する

# サーバーがデフォルトを処理するようにする
{
  "sandbox": true,  // シンプルな自動化
  "prompt": "your task"
}

チェック3: 最新バージョンに更新する

# v1.2+には権限エラーを防止するためのスマートデフォルトが含まれています
npm install -g @cexll/codex-mcp-server@latest

一般的な問題

問題1: MCPツールのタイムアウトエラー Codex MCPツールを使用しているときにタイムアウトエラーが発生した場合は、以下のコマンドを実行します。

# MCPツールのタイムアウト環境変数を設定する (ミリ秒)
export MCP_TOOL_TIMEOUT=36000000  # 10時間

# Windows (PowerShell):
$env:MCP_TOOL_TIMEOUT=36000000

# Windows (CMD):
set MCP_TOOL_TIMEOUT=36000000

これをシェルプロファイル (~/.bashrc, ~/.zshrc, またはPowerShellプロファイル) に追加して、永続的に設定します。

問題2: Codexがファイルを書き込めない Codexが "Operation blocked by sandbox policy" または "rejected by user approval settings" のような権限エラーで応答した場合は、Codex CLIの設定を構成します。 ~/.codex/config.tomlを作成または編集します。

# 動的に生成されるCodex設定
model = "gpt-5-codex"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"
approval_policy = "never"
sandbox_mode = "danger-full-access"
disable_response_storage = true
network_access = true

⚠️ セキュリティ警告: danger-full-accessモードはCodexに完全なファイルシステムアクセスを付与します。信頼できる環境で、完全に理解したタスクにのみこの設定を使用してください。

設定ファイルの場所:

• macOS/Linux: ~/.codex/config.toml
• Windows: %USERPROFILE%\.codex\config.toml

設定を更新した後、MCPクライアント（Claude Desktop、Claude Codeなど）を再起動します。

基本的な例

• use codex to create and run a Python script that processes data
• ask codex to safely test @script.py and explain what it does

デフォルトの動作:

• すべてのcodex execコマンドには自動的に--skip-git-repo-checkが含まれており、不要なgitリポジトリチェックを回避します。すべての実行環境がgitリポジトリであるわけではないためです。
• これにより、非gitディレクトリでCodexを実行するときや、gitチェックが自動化に干渉する場合の権限エラーを防止します。

高度な例

// 特定のモデルでask-codexを使用
'ask codex using gpt-5 to refactor @utils/database.js for better performance';

// 制約付きのアイデア出し
"brainstorm solutions for reducing API latency with constraints: 'must use existing infrastructure, budget under $5k'";

// 構造化編集のための変更モード
'use codex in change mode to update all console.log to use winston logger in @src/';

ツール (AI用)

これらのツールは、AIアシスタントが使用するために設計されています。

コアツール

• ask-codex: codex execを介してCodexにプロンプトを送信します。

  • @ファイル参照をサポートし、ファイル内容を含めることができます
  • オプションのmodelパラメータ - 利用可能なモデル:
    • gpt-5-codex (デフォルト、コーディングに最適化)
    • gpt-5 (汎用、高速推論)
    • o3 (最も賢い、深い推論)
    • o4-mini (高速かつ効率的)
    • codex-1 (ソフトウェアエンジニアリング用のo3ベース)
    • codex-mini-latest (低レイテンシーのコードQ&A)
    • gpt-4.1 (利用可能)
  • sandbox=trueで--full-autoモードを有効にします
  • changeMode=trueで構造化されたOLD/NEW編集を返します
  • 承認ポリシーとサンドボックスモードをサポートします
  • 自動的に--skip-git-repo-checkを含める 非git環境での権限エラーを防止します

• brainstorm: 構造化された方法で新しいアイデアを生成します。

  • 複数のフレームワーク: 発散的、収束的、SCAMPER、デザイン思考、横断的
  • ドメイン固有のコンテキスト (ソフトウェア、ビジネス、クリエイティブ、研究、製品、マーケティング)
  • ask-codexと同じモデルをサポート (デフォルト: gpt-5-codex)
  • アイデアの数と分析の深さを設定可能
  • 実現可能性、影響、革新性のスコアリングを含む
  • 例: brainstorm prompt:"ways to improve code review process" domain:"software" methodology:"scamper"

• ping: メッセージをエコーバックするシンプルなテストツールです。

  • MCP接続が正常に動作していることを確認するために使用します
  • 例: /codex-cli:ping (MCP) "Hello from Codex MCP!"

• help: Codex CLIのヘルプテキストと利用可能なコマンドを表示します。

高度なツール

• fetch-chunk: changeModeの応答からキャッシュされたチャンクを取得します。

  • 大規模な構造化編集応答のページングに使用します
  • cacheKeyとchunkIndexパラメータが必要です

• timeout-test: タイムアウト防止のためのテストツールです。

  • 指定された期間（ミリ秒）実行されます
  • 長時間実行される操作のテストに役立ちます

スラッシュコマンド (ユーザー用)

これらのコマンドは、Claude Codeのインターフェイスで直接使用できます (他のクライアントとの互換性はテストされていません)。

• /analyze: Codexを使用してファイルまたはディレクトリを分析するか、一般的な質問をします。
  • prompt (必須): 分析プロンプト。@構文を使用してファイルを含めることができます (例: /analyze prompt:@src/ summarize this directory) または一般的な質問をすることができます (例: /analyze prompt:Please use a web search to find the latest news stories)。
• /sandbox: Codexの承認モードでコードまたはスクリプトを安全にテストします。
  • prompt (必須): コードテスト要求 (例: /sandbox prompt:Create and run a Python script that processes CSV data または /sandbox prompt:@script.py Test this script safely)。
• /help: Codex CLIのヘルプ情報を表示します。
• /ping: サーバーへの接続をテストします。
  • message (オプション): エコーバックするメッセージ。

📚 ドキュメント

最近の更新

v1.2.4 (2025-10-27)

🔧 主要な改善:

• Windows互換性の強化: Node.jsのネイティブspawn()を業界標準のcross-spawnパッケージに置き換えました。
  • 原因: 以前のshell: trueの修正でも、一部のWindows構成で失敗していました。
  • 解決策: cross-spawn (週間ダウンロード数5000万以上、Webpack/Jestで使用されている) を使用して、自動的にWindowsの.cmdを処理します。
  • 利点:
    • Windowsユーザーにはゼロ設定が必要ありません。
    • .cmd, .ps1, .exe拡張子を自動的に処理します。
    • CMDとPowerShellの両方の環境と互換性があります。
    • パフォーマンスオーバーヘッドは<5msです。
  • 依存関係: cross-spawn@^7.0.6と@types/cross-spawnを追加しました。

🐛 バグ修正:

• Windows固有の4段階のトラブルシューティングガイドでENOENTエラーの診断を強化しました。
• TypeScriptのstrictモードでnull値を処理するために、stdout/stderrにオプションチェーンを追加しました。

📝 ドキュメント:

• ドキュメントに包括的なWindowsトラブルシューティングセクションを追加しました。
• spawn codex ENOENTエラーの解決手順を文書化しました。

v1.2.3 (2025-10-27)

🐛 バグ修正:

• Windows互換性: 適切にインストールされているにもかかわらず、WindowsでCodex CLIの検出が失敗する問題を修正しました。
  • 原因: shell: falseでspawn()を使用すると、Windowsで.cmd拡張子を解決できませんでした。
  • 解決策: クロスプラットフォームのコマンド実行のためにシェルモードを有効にしました。
  • 影響: パフォーマンスへの影響はゼロです (~10msのオーバーヘッド)、配列形式の引数でセキュリティを維持します。
  • 検証されたプラットフォーム: GitHub Actions CIを介して、Windows、macOS、Linuxで検証されました。

📝 ドキュメント:

• すべてのパッケージ参照を@trishchuk/codex-mcp-toolから@cexll/codex-mcp-serverに更新しました。
• クロスプラットフォームのセットアップ手順を強化しました。

🔍 テスト:

• CI/CDで、Ubuntu、macOS、WindowsのNode.js 18.x、20.x、22.xで検証するようになりました。

v1.2.2 以前

• 権限エラーを防止するためのスマートなサンドボックスモードのデフォルト設定
• トラブルシューティングのためのデバッグ情報の強化
• 非git環境のための自動--skip-git-repo-checkフラグ
• 機能フラグによるウェブ検索の統合
• ページネーションサポート付きの構造化変更モード

プラットフォームサポート

最小要件:

• Node.js v18.0.0以上
• Codex CLIがインストールされ、認証されていること (npm install -g @openai/codex)

謝辞

このプロジェクトは、jamubc/gemini-mcp-toolの優れた仕事に触発されています。元のMCPサーバーアーキテクチャと実装パターンを提供してくれた@jamubcに特別な感謝を送ります。

コントリビューション

コントリビューションは歓迎されます！GitHubを通じてプルリクエストを送信するか、問題を報告してください。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

免責事項: これは非公式のサードパーティツールであり、OpenAIと関連付けられておらず、承認もされておらず、後援もされていません。