🧩

Claude Code から Codex を MCP 連携する手順（codex-mcp の 404 にハマった話）

に公開
Node.js
WSL
Model Context Protocol
Claude
Codex
tech

この記事で書くこと

  • Claude Code（Claude CLI）から Codex CLI を MCP サーバとして接続する手順
  • claude mcp add codex-mcp codex mcp-server が上手くいかなかった理由
  • npx codex-mcp で E404 が出るエラーの扱い（分かる範囲で）

環境

  • WSL2 / Ubuntu
  • Node.js: v22.16.0（nvm）
  • Codex CLI: codex-cli 0.77.0
  • Claude Code: 2.0.76 (Claude Code)

確認コマンド：

codex --version
claude --version
which codex

まず結論：正しい追加コマンドはこれ

最終的に これで接続できた。

claude mcp add --transport stdio codex --scope user -- codex mcp-server
claude mcp list

ポイントは --transport stdio と、コマンドを渡すための -- 区切り。

ハマった1：claude mcp add codex-mcp codex mcp-server だとダメ

最初にこうやると上手くいかなかった：

claude mcp add codex-mcp codex mcp-server

なぜダメだったか（推測を含む）

Claude Code の mcp add は、MCP サーバを どう起動するか（transport） と、起動コマンド を明示する必要がある。

  • --transport stdio を指定しないと、Claude 側が期待する形式でプロセスを起動できない（or 別形式として解釈される）
  • -- が無いと、codex mcp-server が「MCP サーバ起動コマンド」として渡らず、引数パースが崩れることがある

そのため、次の形で明示するのが安定：

claude mcp add --transport stdio <サーバ名> --scope user -- <起動コマンド>

ハマった2：npx codex-mcp で E404（パッケージが見つからない）

試したコマンド：

npx codex-mcp

出たエラー（抜粋）：

npm error code E404
npm error 404 Not Found - GET https://registry.npmjs.org/codex-mcp - Not found
npm error 404 'codex-mcp@*' is not in this registry.
npm error 404 Note that you can also install from a tarball, folder, http url, or git url.
npm error A complete log of this run can be found in: /home/hanwia3/.npm/_logs/2025-12-24T22_58_57_879Z-debug-0.log

これについて分かること（書ける範囲）

  • npm レジストリに codex-mcp という名前のパッケージが 見つからないため、npx codex-mcp は成立しない
  • つまり「codex-mcp という npm パッケージを入れて解決する」方向は誤りだった

※ codex 自体は @openai/codex で入るので、こちらが正ルート。

解決手順：Codex CLI を入れて、MCP サーバとして Claude Code に追加する

1) Codex CLI をインストール

npm install -g @openai/codex
codex --version

2) Codex にログイン

codex login

（この手順が抜けると、MCP 起動時に認証で詰まることがある）

3) Claude Code 側で MCP サーバとして追加（stdio）

claude mcp add --transport stdio codex --scope user -- codex mcp-server
  • codex は Claude 側で表示される “サーバ名”
  • --scope user はユーザースコープ（全プロジェクト）に追加したい場合

4) 接続確認

claude mcp list

成功すると codex が Connected になる（playwright と同じ並びで出る）。

うまくいかない時のチェック（よくある原因）

A. codex が見つからない（PATH 問題）

シェルでは which codex が通っても、Claude Code 側の PATH が違うことがある。

which codex
# 例: /home/hanwia3/.nvm/versions/node/v22.16.0/bin/codex

この場合は 絶対パスで登録すると安定：

claude mcp remove codex
claude mcp add --transport stdio codex --scope user -- /home/hanwia3/.nvm/versions/node/v22.16.0/bin/codex mcp-server

B. まず状態を全部出す

切り分けに便利：

codex --version
claude --version
claude mcp list
which codex

まとめ

  • npx codex-mcp の E404 は「そういう npm パッケージが無い」系のエラーで、直しようがない
  • 正攻法は @openai/codex を入れて codex mcp-server を Claude Code に stdio MCP として追加すること
  • claude mcp add --transport stdio ... -- codex mcp-server の形にすると通る

おまけ：今回使ったコマンド一覧（そのまま）

npx codex-mcp

npm install -g @openai/codex
codex --version
codex login

codex --version
claude --version
claude mcp list
which codex

claude mcp add --transport stdio codex --scope user -- codex mcp-server
claude mcp list

Discussion