github-mcp-server-rs

GitHub MCP server (Model Context Protocol) — auth-worker の Device Authorization Grant (RFC 8628) クライアント実装。 Claude Code / Claude Desktop などの MCP host から GitHub API を叩く用途で、ippoan/auth-worker の MCP OAuth Provider と組で動く。

Status: Phase 7 — relay subcommand (issue #27) で outbound WebSocket relay 経由で Streamable HTTP MCP server を mcp(-staging).ippoan.org 配下に公開。auth-worker #117 と pair。

動作の全体像

┌───────────────────────────────────────────────────────────────────┐
│ 1. github-mcp-server-rs auth --env staging                        │
│      → POST /mcp/device_authorization                             │
│      ← device_code / user_code (BCDF-GHJK) / verification_uri     │
│                                                                   │
│ 2. ブラウザで verification_uri_complete を開く                      │
│      → /device → user_code 確認 → Approve                          │
│      → GitHub OAuth (read:user) → /mcp/device_callback             │
│      → ACL pass → KV に github_token を AES-256-GCM 暗号化保存      │
│                                                                   │
│ 3. binary が POST /mcp/token を polling                            │
│      ← 200 { access_token (JWT), refresh_token, scope, expires_in }│
│      → ~/.config/github-mcp-server-rs/token-staging.json に保存     │
│                                                                   │
│ 4. github-mcp-server-rs whoami --env staging                      │
│      → POST /mcp/introspect (Bearer = INTERNAL_SHARED_SECRET)      │
│      ← 200 { active: true, github_login, github_token, ... }       │
│      → GitHub /user を github_token で叩いて login 表示             │
└───────────────────────────────────────────────────────────────────┘

Quick start (staging で先行検証)

前提

• Rust 1.75+ (rustup install stable)
• ippoan/auth-worker が staging deploy 済み (auth-staging.ippoan.org)
• GitHub login が GITHUB_MCP_USER_ALLOWLIST に登録されている (staging default = ["yhonda-ohishi"])

INTERNAL_SHARED_SECRET は release binary に build-time embed されているので、 Releases から download した binary を使う場合は何も設定不要。手元で cargo build する場合の解決順は Secret resolution order 参照。

Build

cd ~/rust/github-mcp-server-rs
cargo build --release
ln -sf "$(pwd)/target/release/github-mcp-server-rs" ~/.local/bin/  # optional

Staging — 認証 (一度だけ)

./target/release/github-mcp-server-rs auth --env staging
# → ブラウザで verification_uri_complete を開く
# → GitHub OAuth → "認証完了" 画面
# → binary 側: "✓ Token saved to ~/.config/github-mcp-server-rs/token-staging.json"

Staging — token 確認 (whoami)

./target/release/github-mcp-server-rs whoami --env staging
# → /mcp/introspect で github_token を取り出し、GitHub /user に投げて login を表示
# 期待出力:
#   ✓ Introspect OK:
#     sub:          github:yhonda-ohishi
#     github_login: yhonda-ohishi
#     scope:        mcp.read mcp.write
#   ✓ GitHub /user OK:
#     login: yhonda-ohishi
#     id:    <numeric>

Prod に切り替えるとき

prod 環境が準備済 (auth-worker issue #97) になったら:

./target/release/github-mcp-server-rs auth --env prod
./target/release/github-mcp-server-rs whoami --env prod

staging / prod の token cache は別 file (token-staging.json / token-prod.json) なので 両方並列で持てる。

Subcommands

MCP server mode (relay)

v0.0.6+ から、MCP server は outbound WebSocket relay で公開する (issue #27、auth-worker #117 と pair)。 旧 serve (cloudflared 用 axum bind) は撤廃。

auth でログイン済みの状態で relay を起動すると:

1. `/mcp/introsp

... View full README on GitHub