GitHub MCPサーバーの使い方 — Claude CodeでのIssue・PR自動化

GitHub MCPサーバーは、GitHub自身が公開する公式MCPサーバーです。Issueやプルリクエストの読み書き、GitHub Actionsのログ確認、コードスキャンの結果参照までを、Claude Codeから自然文の指示で実行できます。Claude CodeはghコマンドをBashツール経由で呼べます。MCPサーバーは、ツール呼び出し単位で権限を絞れる点と、GitHub Actions・Dependabot・Secret Scanningのような構造化データを直接扱える点で役割が異なります。

この記事では、接続方式の選び方、トークンを共有ファイルに残さない書き方、有効にする機能範囲(toolsets)の絞り方、読み取り専用に固定するread-onlyモードまでを扱います。コマンドの出力はClaude Code v2.1.287で確かめたものです。MCPプロトコル自体の仕組みはMCPとはにあります。権限ルールの一般的な書き方はMCPセキュリティガイドが対応します。

GitHub MCPサーバーとは

リポジトリの閲覧・検索、Issue / PRの作成と管理、コミット履歴の分析ができます。GitHub Actionsのワークフロー監視や、Dependabotアラート・コードスキャン結果の確認もできます。いずれもツール呼び出しとして提供されます。接続先は2種類あります。GitHubがホストするリモートサーバーと、Dockerやバイナリでローカルに立てるサーバーです。

状況別に接続方式を選ぶ

リモート側でOAuthを使う接続は、ホストアプリ(接続する側)がGitHub AppかOAuth Appを登録していることが前提です。Claude Desktopのカスタムコネクタ経由では、このOAuth認証が現状サポートされていません。そのためGitHub側のガイドは、Claude Desktopにはローカル(Docker)構成を案内しています。Claude Codeでの失敗の原因と対処はGitHub MCPサーバーのOAuth接続エラーで扱っています。

リモートサーバーを追加して接続を確かめる

トークンを直接渡す最小の形は、次のとおりです。

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

トークンの実値は、追加したスコープの設定にそのまま保存されます。ローカルスコープ(既定)なら~/.claude.jsonです。

.mcp.jsonに実際に書き出される内容

チームで共有するなら--scope projectを付けます。ここで${GITHUB_PAT}を二重引用符の中でシェルに展開させず、参照のまま渡すのがポイントです。作業用の空ディレクトリで実行した結果を示します。

claude mcp add --transport http --scope project github \
  https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer \${GITHUB_PAT}"

出力は次のようになります。ヘッダーの値は伏せ字で表示されます。

Added HTTP MCP server github with URL: https://api.githubcopilot.com/mcp to project config
Headers: {
  "Authorization": "[REDACTED]"
}
File modified: ./.mcp.json

生成された.mcp.jsonは次のとおりです。URL末尾のスラッシュは、出力のメッセージでは落ちていますが、ファイルには入力どおり残っています。

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

この形ならファイルをコミットしても、トークンはリポジトリに入りません。各メンバーは自分の環境変数GITHUB_PATを設定するだけで済みます。未設定の変数があるときは、${VAR}の文字列がそのまま使われ、claude mcp listと/mcpに警告が出ます。

変数名には注意点があります。リモートサーバーのurlとheadersでは、決められた名前が空として読まれます。ANTHROPIC_API_KEYやNPM_TOKEN、AWS_BEARER_TOKEN_BEDROCKやHTTPS_PROXYなどがその例です。Bearer ${NPM_TOKEN}と書くとBearer だけが送られ、多くは401で失敗します。API_KEYやGITHUB_PATのように自分で付けた名前なら、書いたとおりに展開されます。

プロジェクトスコープのサーバーは、対話セッションで初めて使うときに承認を求められます。承認前のclaude mcp listではPending approvalと表示され、接続されません。

ローカルサーバーを使う(Docker)

GitHub Enterprise Serverに接続する場合や、トークンを発行せずにログインで済ませたい場合はローカルを使います。github.com向けの公式イメージは、ブラウザーでの初回ログイン後、トークンをメモリ上にだけ保持します。Docker内のサーバーにログインのコールバックを届けるため、固定ポートをループバックに公開します。

claude mcp add github -e GITHUB_OAUTH_CALLBACK_PORT=8085 \
  -- docker run -i --rm -p 127.0.0.1:8085:8085 \
  -e GITHUB_OAUTH_CALLBACK_PORT ghcr.io/github/github-mcp-server

PATで認証したいときはGITHUB_PERSONAL_ACCESS_TOKENを渡します。設定するとOAuthより優先されます。

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT \
  -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

--より前がClaude Code自身のオプションで、後ろがサーバー起動コマンドです。-eのあとにサーバー名を直接置くと、名前が環境変数の組として読まれて失敗します。上のように--の前に別のオプションを挟むか、名前を先に書きます。Dockerを使わない場合は、リリースバイナリをPATHに置き、add-jsonのcommandとargsにstdioを指定します。

toolsetsで有効にする範囲を絞る

GitHub MCPサーバーの機能はtoolsetsという単位でグループ化されています。何も指定しなければ、context(現在のユーザーとGitHubの文脈。READMEが強く推奨)、repos、issues、pull_requests、usersの5つだけが有効です。

Actionsやコードスキャンを扱うには、actionsやcode_securityを足します。ほかにdependabot、discussions、gists、git、labels、notifications、orgs、copilotがあります。さらにprojects、secret_protection、security_advisories、stargazers、code_quality、governanceも使えます。copilot_issue_intentsは、Copilotへのイシュー割り当てツールを意図メタデータ付きで提供するオプトイン用です。

ローカルサーバーでは、フラグまたは環境変数で指定します。

GITHUB_TOOLSETS="default,actions,code_security" ./github-mcp-server

リモートサーバーではHTTPヘッダーで指定します。ヘッダーが複数になる場合は、JSONで書けるclaude mcp add-jsonが書きやすい方法です。

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer ${GITHUB_PAT}","X-MCP-Toolsets":"default,actions,code_security"}}'

URLのパスでも指定できます。リモートサーバーは/x/{toolset}で特定のtoolsetだけを、/readonlyで読み取り専用を、それぞれヘッダーなしで選べます。両方を組み合わせた/x/all/readonlyのような書き方もできます。ヘッダーを足しにくいホストで便利です。

リモートサーバーだけが持つtoolsetsはcopilot_spacesとgithub_support_docs_search(GitHubの製品・サポート文書の検索)です。ローカルのDocker版だけを使っている場合、この2つは選択肢に出ません。

トークンの種類でも見える範囲が変わります。classic PAT(ghp_で始まる)では、起動時にトークンのスコープから使えないツールが取り除かれます。リモートのOAuthでは、足りないスコープが必要になった時点で追加の認可を求められます。classic PATのスコープ検出に失敗した場合は、警告を出して全ツールを残します。fine-grained PATは、この絞り込みの対象外です。READMEには、トークンで使えないツールが表示されうると書かれています。

ツール選択の優先順位

絞り込みの設定は組み合わせられます。ぶつかったときは次の順で効きます。

read-onlyモードとlockdownモードの違い

名前が似た2つの機構ですが、守る対象が違います。

lockdownは、公開リポジトリのIssueなど外部の人が書ける場所からのプロンプトインジェクションを減らすためのものです。公式ドキュメントは、これをベストエフォートの内容フィルターであり、認可の境界ではないと明記しています。資格情報が元々読み書きできる範囲は変わらず、応答から外れた内容に別のツールやGitHub APIから届く余地も残ります。github-actions[bot]とcopilotが書いた内容は、push権限に関係なく安全として扱われます。

サーバー側でlockdownを有効にしている場合、リクエストのX-MCP-Lockdownヘッダーで無効に戻すことはできません。ヘッダーで有効にできるのは、サーバー側が有効にしていないときだけです。

コードレビューや調査にだけ使わせたいときは、read-onlyにして.mcp.jsonに別名で足しておくと、書き込み用と使い分けられます。次は、実際にadd-jsonで追加した結果です。

claude mcp add-json --scope project github-ro '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer ${GITHUB_PAT}","X-MCP-Readonly":"true"}}'

Added http MCP server github-ro to project config

.mcp.jsonのmcpServersにgithub-roが加わり、headersにAuthorizationとX-MCP-Readonlyが並びます。先に作ったgithubはそのまま残ります。同じ名前を複数のスコープに別のエンドポイントで置くと警告が出るので、別名にするのが安全です。

確実に遮断したい操作には、read-onlyか、Claude Code側の権限ルール(mcp__github__*単位のdeny設定)を使います。権限ルールはサーバー側の設定を書き換えず、Claude Codeが呼び出しを止めるだけです。lockdownは、この役割を担いません。複数の組織で使い分けるときは、サーバー名をgithub-workのように変え、トークンを分けて追加します。ほかのMCPサーバーの選び方はおすすめMCPサーバー10選にあります。Claude Code全体の設定はClaude Codeの完全ガイドです。

つまずきの原因と見分け方

症状ごとに、原因を切り分けます。

• 同じツールが二重に見える: 同じサーバーを別の名前で二重に登録していないか、claude mcp listで見ます
• サーバーが起動しない: --toolsやX-MCP-Toolsに存在しないツール名を書くと起動に失敗します。綴りは公式のツール一覧と照らします
• PowerShellでmissing required argument 'name'が出る: サーバー名をclaude mcp addの直後に置きます。Windowsではadd-jsonがInvalid inputを返すことがあります。その場合は--transport http形式のclaude mcp addを使います

よくある質問

有効なtoolsetsは後から変えられますか

リモートはclaude mcp remove githubで消して、X-MCP-Toolsetsの値を変えてadd-jsonし直します。ローカルはGITHUB_TOOLSETSを書き換えて再起動します。

まとめ

最初に決めるのは、書き込みを任せるサーバーと、読み取りだけのサーバーを別の名前で分けておくかどうかです。分けておけば、toolsetsを足すときもread-onlyの側に手が及びません。