github-mcp-proxy

Cloudflare Workers上で動作する、個人/小規模チーム向けのGitHub MCPサーバーです。AIエージェントに対してリポジトリ単位のガードレールを提供します。

MCP対応のあらゆるエージェント（Claude、Codex、ChatGPT、Cursor、Clineなど）を接続でき、どのリポジトリに、どのようにアクセスできるかを厳密に制御可能です。

[!WARNING] セキュリティや安定性が必要な場合は、公式のGitHub MCPサーバーを使用してください。 フォークは自由ですが、フォーク後のセキュリティ問題については自己責任となります。

なぜこれが必要か

一般的なGitHubトークンをエージェントに渡すと、アカウント全体へのフルアクセス権を与えてしまいます。このサーバーは、その権限を以下のように制限します：

• リポジトリ単位の権限レベル — read / issues / full

• ブランチ保護 — 新規ブランチは特定のプレフィックス（デフォルトは claude/）と一致する必要があり、main/masterへの書き込みは常に禁止

• コミットメッセージポリシー — Conventional Commitsをサーバーサイドで検証

• ラベルのホワイトリスト — リポジトリごとに allowedLabels を設定。サーバーはGitHub上で自動的にラベルを作成しません

• 禁止パス — .github/workflows/** は常にブロック

• 監査証跡 — 書き込みのたびに Signed-off-by / Assisted-by トレーラー、またはエージェントとモデルを識別するフッターが自動的に付与されます

Related MCP server: Kontrol

アーキテクチャ

 MCP agent ──(Streamable HTTP + OAuth)──▶ Cloudflare Worker
                                              │
                                              ├── workers-oauth-provider  (OAuth 2.1 server to MCP clients)
                                              ├── GitHub OAuth            (OAuth client to github.com)
                                              ├── KV                      (session tokens)
                                              ├── Durable Object          (MCP agent state)
                                              └── Octokit                 (GitHub REST)

設定（ghmcp.config.ts）はデプロイ時にWorkerにバンドルされます。実行時のKV読み取りは発生せず、satisfies を通じて型チェックが行われます。

クイックスタート

git clone <your-fork>
cd kz-github-mcp
npm install
cp ghmcp.config.sample.ts ghmcp.config.ts   # edit: repos you want to expose
cp wrangler.sample.jsonc wrangler.jsonc      # edit: KV id + worker name
cp .env.example .env                         # edit: for local dev only

GitHub OAuth Appを作成し（ホームページ = https://<worker>.<subdomain>.workers.dev、コールバック = /callback）、以下を実行します：

wrangler kv namespace create "OAUTH_KV"      # add the id to wrangler.jsonc
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY    # openssl rand -hex 32
npm run deploy

ローカル開発：http://localhost:8788 を指す2つ目のOAuth Appを作成し、.env に認証情報を設定して npm run dev を実行します。

継続的デプロイ（オプション）

.github/workflows/deploy.yml は、main へのプッシュごとにCloudflareへデプロイします。GitHubの「Settings」→「Secrets and variables」→「Actions」で、以下の2つのリポジトリシークレットを設定してください：

GitHub OAuthの認証情報（GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, COOKIE_ENCRYPTION_KEY）は、GitHub Actionsではなく、Worker自体の Wrangler シークレットとして保持されます。wrangler secret put で一度設定するだけで済みます。

仕組みについては docs/ARCHITECTURE.md を、各設定項目については docs/CONFIG.md を参照してください。

AIエージェントの接続

Claude (claude.ai) — 「Settings」→「Connectors」→「Add custom connector」→ https://<worker>.<subdomain>.workers.dev/sse を貼り付けます。

Claude Code / Codex / Cursor / Cline — クライアントのMCP設定に追加します：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["mcp-remote", "https://<worker>.<subdomain>.workers.dev/sse"]
    }
  }
}

その他のMCPホスト — 同じ /sse エンドポイントを指定します。初回接続時にOAuthフローが実行されます。

エージェントにツールの正しい使い方を教えるには、SKILL.md をシステムプロンプト、プロジェクトの指示、またはスキルディレクトリに含めてください。

ツール

ghmcp_ というプレフィックスが付きます。各ツールは最小権限レベルを宣言しており、サーバーはそれ以下の権限での呼び出しを拒否します。

設定の disabledTools を通じて、任意のツールを無効化できます。

検証

npm run validate-config

gh CLIを使用して、ghmcp.config.ts 内のすべてのリポジトリが存在すること、および allowedLabels 内のすべてのラベルがGitHub上に存在することを確認します。prebuild フックとして自動実行されるため、タイプミスがあると npm run build が失敗します。

ライセンス

元々は cloudflare/ai/demos/remote-mcp-github-oauth からフォークされました。MITライセンスです。

本ツールはMITライセンスの下で提供されています。詳細は LICENSE を参照してください。