GitHub MCP を繋いで Issue 一覧を取る

学習のねらい

これまでのレッスンで、Claude Agent SDK と MCP の基礎、そして自作 MCP サーバーの作り方を学びました。 本レッスンでは、公式に公開されている GitHub MCP サーバー を Claude Agent SDK に接続し、AI エージェントが GitHub の Issue 一覧を取得するタスクを実行してみましょう。 これにより、AI エージェントが外部の複雑なシステムと連携する具体的な手順と、その際の認証の重要性を実践的に理解します。

GitHub MCP サーバーの起動方法

GitHub の Issue/PR 操作を MCP 経由で行うための公式サーバーは GitHub 公式の github-mcp-server です (Docker イメージとして配布されており、ローカルに Docker があれば追加のインストール作業なしで起動できます)。旧来の @modelcontextprotocol/server-github (npm パッケージ) は2025年5月にアーカイブ済みのため、現在は使いません。

事前に、GitHub Personal Access Token を発行し、環境変数に設定しておきます (最小権限として repo の読み取りスコープで十分です)。

export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Claude Agent SDK からどう繋ぐか

Claude Agent SDK から外部の stdio MCP サーバーに接続するには、ClaudeAgentOptions の mcp_servers に command / args / env を指定します。

import asyncio
import os
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "github": {
                "command": "docker",
                "args": [
                    "run", "-i", "--rm",
                    "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
                    "ghcr.io/github/github-mcp-server",
                ],
                "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ["GITHUB_PERSONAL_ACCESS_TOKEN"]},
            }
        },
        allowed_tools=["mcp__github__list_issues"],
    )

    async for message in query(
        prompt="anthropics/claude-code リポジトリの直近のオープンな Issue を3件教えて",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)

asyncio.run(main())

ポイントは2つです。

1. mcp_servers にサーバーの起動コマンドを渡すだけで接続できる: 自分で MCP プロトコルのメッセージをやり取りするコードは不要です。SDK が裏で tools/list / tools/call を処理します。
2. allowed_tools で明示的に許可しないとツールは使われない: MCP ツールの名前は mcp__<サーバー名>__<ツール名> という形式になります (例: mcp__github__list_issues)。許可リストに入れないと、Claude はツールの存在を認識しても呼び出しません。

Issue 一覧の取得と表示

エージェントに投げるプロンプトは自然言語で構いません。Claude が内部で「list_issues ツールを、owner/repo を引数にして呼び出す必要がある」と判断し、mcp__github__list_issues を呼び出します。

接続が成功しているかどうかは、system メッセージ (subtype == "init") の中の mcp_servers フィールドで確認できます。

if isinstance(message, SystemMessage) and message.subtype == "init":
    print("MCP servers:", message.data.get("mcp_servers"))

各サーバーの status が "connected" になっていればOKです。"failed" の場合は、環境変数 (GITHUB_PERSONAL_ACCESS_TOKEN) や Docker のインストール状況を確認してください。

まとめ

このレッスンでは、GitHub 公式の github-mcp-server を Docker で起動し、ClaudeAgentOptions.mcp_servers に command/args/env を指定するだけで Claude Agent SDK から接続できることを学びました。allowed_tools でツールを明示的に許可する必要がある点、接続状況は init メッセージで確認できる点を押さえておきましょう。 次の演習では、実際に自分の GitHub リポジトリの Issue 一覧を Claude エージェントに取得させてみましょう。

（最終検証日: 2026-07。公式リポジトリ: https://github.com/github/github-mcp-server ）

---