WSL2 + Docker + CodexCLIで GitHub MCP を動かすまで

Last updated at 2025-09-30Posted at 2025-09-30

この記事は、Windows（WSL2: Ubuntu）で CodexCLI →（Docker）→ GitHub MCP サーバ を動かすまでの詰まり→原因→解決を、初心者向けに誰でもわかるようまとめたものです。
自分が実際にハマったポイント（WSL連携 / PATH / TTY / トークン）をコマンドの意味など噛み砕いて書きました。
「今まさに詰まってる人」がそのまま追体験できる構成にしています。

ゴール（この記事でできるようになること）

端末でこう言うだけ：

codex "Use the **github** MCP tool to list the first 5 repositories I can access, and print only the names."

裏で CodexCLI が Docker コンテナの GitHub MCP サーバを自動起動
リポ名 / Issues / PR などを自然文で取得（＝tool success が出る）

まずは超ざっくり構成図

あなたの端末(CodexCLI)
        │  stdio（標準入出力）
        ▼
  GitHub MCP サーバ（Dockerコンテナ）
        │  GitHub API（PATで認証）
        ▼
       GitHub

**stdin/stdout（stdio）**という“ホース”で、CodexCLI ↔ MCPサーバが会話します。

用語（最初に一読だけでOK）

CLI：文字で操作するツール（ここでは codex）。
MCP (Model Context Protocol)：AIと外部ツールを安全・標準に繋ぐ規格（USB-Cみたいな“共通口”）。stdioで繋ぐのが基本。
Docker：アプリをコンテナ（小さな箱）で動かす仕組み。
　イメージ＝設計図 / コンテナ＝起動した実体。
PAT (Personal Access Token)：GitHubの“鍵”。
　権限（スコープ）と期限を最小に。
TTY：対話型の“ちゃんとした端末”。CLIによってはTTYが無いとUI系でコケる。
PATH：端末がコマンドを探すフォルダの順序（which dockerで今どれを使ってるか分かる）。

体験談：ここで詰まった→こう解いた（実ログつき）

1) `docker` が WSL(Ubuntu) から見えない問題

症状

which docker
# -> /mnt/c/Program Files/Docker/...（Windows側のdocker.exeを指してる）
docker --version
# “WSL統合してください” 的なメッセージ

原因

Docker Desktop の WSL Integration がOFF
あるいは WSL 側で Windows版 docker.exe を拾ってしまう（PATH順の問題）

解決

Docker Desktop → Settings → Resources → WSL Integration で Ubuntu を ON。
（ON→OFF→ON し直して Apply & Restart すると確実）
WSLで PATH を優先する：
```
# 一時的（このシェルのみ）
export PATH="/mnt/wsl/docker-desktop/cli-tools/usr/bin:$PATH"
which docker
docker version
docker run --rm hello-world
```
コマンドの意味
- export PATH=...:$PATH：WSL用 docker CLI を優先的に使う設定
- which docker：今使われる docker の本体パスを確認
- docker version：クライアント/サーバ（デーモン）両方の接続確認
- docker run --rm hello-world：Pull→実行→後片付けまでの通し確認

Windows側で wsl --shutdown を実行し、WSLを完全停止→再起動すると連携が整うことがあります。([Microsoft Learn][4])

図：Docker Desktop の WSL Integration 画面のスクショ

2) GitHub MCP サーバの“手動テスト”

目的：コンテナ自体は起動できるか？（トークン・ネット・改行コード・権限の生死判定）

docker pull ghcr.io/github/github-mcp-server:latest

docker run -i --rm --pull=always \
  --env-file "$HOME/.codex/mcp.env" \
  ghcr.io/github/github-mcp-server:latest \
  stdio

コマンドの意味

docker pull ...：イメージ取得（ネット制限の切り分けにも◎）
-i：標準入力を接続（stdioモードに必須）
--rm：終了時にコンテナ自動削除
--pull=always：常に最新を使う
--env-file：PATなどの環境変数をまとめて注入
stdio：標準入出力で会話するモード（MCPの標準）

成功の見え方
GitHub MCP Server running on stdio → 待機状態（Ctrl+Cで終了OK）

3) CodexCLI に MCP サーバ設定（TOML）を教える

~/.codex/config.toml を最小から始めるのが鉄板。WSLの絶対パスを使うのがコツ。

# ~/.codex/config.toml
[mcp_servers.github]
command = "docker"
args = [
  "run","-i","--rm","--pull=always",
  "--env-file","/home/あなたのユーザー名/.codex/mcp.env",
  "ghcr.io/github/github-mcp-server:latest","stdio"
]

ポイント

C:\... や \\wsl.localhost\... はNG。/home/... 形式で。
まずは余計な -e 環境変数を付けない（最小構成で動作確認→徐々に足す）

CodexCLI 公式

概要/導入： https://developers.openai.com/codex/cli/
GitHub： https://github.com/openai/codex

4) CodexCLI から“github”が見えているか確認

codex --version
codex mcp list
codex mcp get github

コマンドの意味

codex --version：CodexCLI 本体が動いているか
codex mcp list：登録済みMCPサーバ一覧（ここに github が出ればOK！）
codex mcp get github：内部で実行する docker run ... stdio の詳細を表示

5) いよいよ実行（`tool success` を出す）

codex "Use the **github** MCP tool to list the first 5 repositories I can access, and print only the names."

ポイント

プロンプト中に “github MCP tool を使って” と明示すると、CodexCLI が裏で Docker を起動して接続します。
別タブで docker ps --filter "ancestor=ghcr.io/github/github-mcp-server:latest" を見ると、コンテナが起動しているのが分かります。

（画像）

図4（ここ）：tool success と返ってきたリポ名の出力
- 置き場所：この節の最後
- 目的：**最終ゴールの“成功ログ”**を見せる
- 注意：プライベート情報（リポ名など）に配慮

便利オプション（安全ファーストで運用）

読み取り専用で始める：
.env か Docker -e で
```
GITHUB_READ_ONLY=1
```
まずは誤操作防止でREAD ONLY → 慣れてから書き込み解禁がおすすめ。
ツールセットを絞る：
```
GITHUB_TOOLSETS=repos,issues,pull_requests
```
使う機能だけにするほど安定＆安全（あとから拡張でOK）。
Approvals（承認フロー）：
読み取り系は自動許可、書き込み系は手動承認にしておくと実運用がラクです。

TTYエラーにハマったら

症状：The cursor position could not be read within a normal duration
理由：CodexCLI のUIがTTY（ちゃんとした端末）を前提にする場面がある
対処：Windows Terminal の WSLタブや VSCode の統合ターミナルなど、実端末で実行する
（非対話/CIモードもありますが、まずは実端末がシンプル）([OpenAI開発者][7])

困ったときの“3つの観点”で切り分け表

現象	原因の観点	直し方
`No MCP tools available.`	設定：`config.toml`の場所/書式/パス	最小例に戻す。`--env-file` は /home/... 絶対パスに
コンテナが即落ちる	認証：PAT無効/権限不足、`.env`がCRLF	PAT再発行・最小スコープ、`dos2unix ~/.codex/mcp.env`、`chmod 600`
`docker: not found`	実行基盤：WSL連携 or PATH順序	Docker DesktopのWSL IntegrationON、PATHに`/mnt/wsl/...` 追加、`wsl --shutdown` で再構成
TTYエラー	端末：非対話環境	“実端末”で実行（Windows Terminal / VSCode Terminal）

参考資料

CodexCLI（GitHub）：https://github.com/openai/codex
MCP 概要（公式サイト）：https://modelcontextprotocol.io/
MCP Transports（stdio / HTTP）：https://modelcontextprotocol.io/docs/concepts/transports
GitHub MCP Server（リポジトリ）：https://github.com/github/github-mcp-server
GitHub MCP Server README（Toolsets / Read-Only / Docker）：https://github.com/github/github-mcp-server#readme
GitHub PAT（作成・権限）：https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
GitHub REST API 認証：https://docs.github.com/rest/overview/authenticating-to-the-rest-api
Docker Desktop × WSL2（WSL統合）：https://docs.docker.com/desktop/features/wsl/
Docker Desktop × WSL2（使い方）：https://docs.docker.com/desktop/features/wsl/use-wsl/
WSL 基本コマンド（wsl --shutdown 等）：https://learn.microsoft.com/en-us/windows/wsl/basic-commands
類似記事：GitHub MCP を WSL で試す（Qiita）：https://qiita.com/k-koga/items/8aa84cff1dbd25f3477b
類似記事：WSL + Docker 連携（Qiita）：https://qiita.com/GeekMasahiro/items/48118b56f44aae63efdd

付録：コマンド一括コピペ

# ▼ Docker/WSL 接続確認
which docker        # どのdockerを使っているか（PATHの実体）を確認
docker version      # CLIとデーモンの接続両方を確認
docker run --rm hello-world  # Pull→起動→出力→終了までの通しテスト

# ▼ （必要なら）WSLでDocker CLIを優先
export PATH="/mnt/wsl/docker-desktop/cli-tools/usr/bin:$PATH"  # WSL用dockerを優先
which docker        # /mnt/wsl/... を指せばOK

# ▼ GitHub MCP Server 手動スモークテスト
docker pull ghcr.io/github/github-mcp-server:latest  # イメージ取得（ネット切り分け）
docker run -i --rm --pull=always \
  --env-file "$HOME/.codex/mcp.env" \
  ghcr.io/github/github-mcp-server:latest \
  stdio                  # stdioモードで待機（Ctrl+Cで終了）

# ▼ CodexCLI 側（MCP認識テスト）
codex --version        # CLIが動作しているか
codex mcp list         # "github"が出れば設定が読まれている
codex mcp get github   # 内部で実行される docker run の詳細を確認

# ▼ 実行（自然文でツールを使う）
codex "Use the **github** MCP tool to list the first 5 repositories I can access, and print only the names."

config.toml（最小例）

[mcp_servers.github]
command = "docker"
args = [
  "run","-i","--rm","--pull=always",
  "--env-file","/home/あなたのユーザー名/.codex/mcp.env",
  "ghcr.io/github/github-mcp-server:latest","stdio"
]

mcp.env（例：読み取り専用で始める）

GITHUB_ACCESS_TOKEN=＜あなたのPAT＞
GITHUB_READ_ONLY=1
GITHUB_TOOLSETS=repos,issues,pull_requests

.envは chmod 600、Windowsで編集したら dos2unix でLF化。
トークン（PAT）は絶対に公開しないでください。

まとめ

正直、最初は「Dockerは動いてるのにCodexCLIから見えない…」で心が折れかけました。
でも、WSL連携→PATH→hello-world→MCP手動起動→Codexの認識→tool success と一本道に分解したら、ちゃんと動くようになってスッと肩の力が抜けました。

この道のりが、今詰まっているあなたの“1歩先の灯り”になれば嬉しいです。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up