github-mcp-server

GitHub MCP サーバーのドキュメント

このファイルでは、ツールや設定オプションを含む GitHub MCP（Model Context Protocol）サーバーについて説明します。

注：このファイルは、github-mcp-tools-report.md ワークフローによって自動生成および更新されます。手動での編集は上書きされる場合があります。

最終更新日：[ワークフローによって入力]

概要

GitHub MCP サーバーは、Model Context Protocol を通じて GitHub の API へのプログラムによるアクセスを AI エージェントに提供します。次の 2 つの動作モードに対応しています。

ローカルモード（Docker ベース）

• GitHub Actions ランナー上で Docker コンテナーとして実行されます
• 認証には GITHUB_PERSONAL_ACCESS_TOKEN 環境変数を使用します
• GITHUB_TOOLSETS 環境変数でツールセットを設定できます
• GITHUB_READ_ONLY 環境変数で読み取り専用モードに対応します

リモートモード（ホスト型）

• ホスト型 GitHub MCP サーバー https://api.githubcopilot.com/mcp/ に接続します
• HTTP ヘッダーで Bearer トークン認証を使用します
• X-MCP-Readonly ヘッダーで読み取り専用モードに対応します
• Docker コンテナーは不要です

設定

基本設定

ローカルモード（Docker）：

tools:
  github:
    mode: "local"
    toolsets: [default]  # or [repos, issues, pull_requests]

リモートモード（ホスト型）：

tools:
  github:
    mode: "remote"
    toolsets: [default]  # or [repos, issues, pull_requests]

読み取り専用モード

GitHub MCP サーバーを読み取り専用操作に制限するには、次のようにします。

tools:
  github:
    mode: "remote"
    read-only: true
    toolsets: [repos, issues]

カスタム認証

デフォルトの代わりにカスタム GitHub トークンを使用します。

tools:
  github:
    mode: "remote"
    github-token: "${{ secrets.CUSTOM_GITHUB_PAT }}"
    toolsets: [repos, issues]

利用可能なツールセット

GitHub MCP サーバーは、ツールを論理的なツールセットにまとめています。特定のツールセットを有効にするか、推奨されるデフォルトを使用するには [default] を、すべてを有効にするには [all] を使用できます。

:::note[ツールセットを使う理由] 個々の GitHub ツールを列挙するための allowed: パターンは、新しいワークフローでは推奨されません。個々のツール名は GitHub MCP サーバーのバージョン間で変更される場合がありますが、ツールセットは安定した API を提供します。必ず toolsets: を使用してください。既存のワークフローの更新方法については、allowed からツールセットへの移行を参照してください。 :::

:::tip[ベストプラクティス] GitHub ツールには必ず toolsets: を使用してください。 ツールセットには次の利点があります。

• 安定性：MCP サーバーのバージョン間でツール名が変更される場合がありますが、ツールセットは安定しています
• 整理のしやすさ：関連する機能が明確にグループ化されています
• 完全な機能：関連するツールをすべて自動的に取得できます
• 記述量の削減：設定が簡潔になります
• 将来への対応：新しいツールは追加時に自動的に含まれます :::

推奨されるデフォルトのツールセット

toolsets: が指定されていない場合、次のツールセットがデフォルトで有効になります。

• context - ユーザーと環境のコンテキスト（強く推奨）
• repos - リポジトリの管理
• issues - Issue の管理
• pull_requests - プルリクエストの操作

注：users ツールセットはデフォルトに含まれていないため、必要な場合は明示的に指定する必要があります。

利用可能なすべてのツールセット

ツールセット	説明	一般的なツール
context	ユーザーと環境のコンテキスト	get_teams, get_team_members
repos	リポジトリ管理	get_repository, get_file_contents, search_code, list_commits
issues	イシュー管理	issue_read, list_issues, create_issue, search_issues
pull_requests	プルリクエスト操作	pull_request_read, list_pull_requests, create_pull_request
actions	GitHub Actions/CI/CD	list_workflows, list_workflow_runs, download_workflow_run_artifact
code_security	コードスキャンとセキュリティ	list_code_scanning_alerts ⚠️（常に state: open と severity: critical,high を含めてください）、get_code_scanning_alert
dependabot	依存関係管理	Dependabot のアラートと更新
discussions	GitHub Discussions	list_discussions, create_discussion
experiments	実験的機能	不安定な API／プレビュー API
gists	Gist 操作	create_gist, list_gists
labels	ラベル管理	get_label, list_labels, create_label
notifications	通知	list_notifications, mark_notifications_read
orgs	組織管理	get_organization, list_organizations
projects	GitHub Projects	プロジェクトボード操作
secret_protection	シークレットスキャン	シークレットの検出と管理
security_advisories	セキュリティアドバイザリ	アドバイザリの作成と管理
stargazers	リポジトリのスター	スター関連の操作
users	ユーザープロフィール	get_me ⚠️（以下の注記を参照）、get_user, list_users
search	高度な検索	リポジトリ、コード、ユーザーを横断した検索

:::caution[get_me はインテグレーショントークンで 403 を返します] エージェント型のワークフローでは、get_me の使用は推奨されません。GitHub Actions のインテグレーショントークン（すべての gh-aw 実行でデフォルト）で呼び出すと、HTTP 403 が返されます。エージェントの本人確認に get_me を呼び出さないでください。

正式な本人確認情報の取得元：<github-context> ブロックは各ワークフローのプロンプトの冒頭に挿入され、actor、repository、run_id などのコンテキスト値を含みます。本人確認情報は必ずここから読み取ってください。 :::

ツールセット別の利用可能なツール

このセクションでは、allowed: から toolsets: への移行を支援するため、各ツールと対応するツールセットを示します。

Context ツールセット

• get_teams - ユーザーが所属するチームの一覧を取得します
• get_team_members - 特定のチームのメンバー一覧を取得します

Repos ツールセット

• get_repository - リポジトリ情報を取得します
• get_file_contents - リポジトリからファイルの内容を読み取ります
• search_code - リポジトリ横断でコードを検索します
• list_commits - リポジトリ内のコミット一覧を取得します
• get_commit - 特定のコミットの詳細を取得します
• get_latest_release - 最新のリリースを取得します
• list_releases - すべてのリリースを一覧表示します

Issues ツールセット

• issue_read - イシューの詳細を読み取ります
• list_issues - リポジトリ内のイシューを一覧表示します
• create_issue - 新しいイシューを作成します
• update_issue - 既存のイシューを更新します
• search_issues - リポジトリ横断でイシューを検索します
• add_reaction - イシューまたはコメントにリアクションを追加します
• create_issue_comment - イシューにコメントを追加します

プルリクエストのツールセット

• pull_request_read - プルリクエストの詳細を読み取ります
• list_pull_requests - リポジトリ内のプルリクエストを一覧表示します
• get_pull_request - 特定のプルリクエストの詳細を取得します
• create_pull_request - 新しいプルリクエストを作成します
• search_pull_requests - リポジトリを横断してプルリクエストを検索します

ワークフローのプロンプト／テンプレートから list_pull_requests を呼び出す場合：

• ページサイズは小さめに設定します（より小さい値または大きい値が妥当な場合を除き、perPage: 10 を使用します）。
• fields_param 機能に対応する GitHub MCP server 1.6.0 以降（Insiders モードでは自動的に有効）では、応答サイズを抑えるために fields: [number, title, state, html_url]（または必要なトップレベルフィールド）を渡します。同じ fields パラメーターは、list_issues、search_issues、search_pull_requests、list_commits、list_releases、search_code でも利用できます。get_file_contents の場合、fields で抑えられるのはディレクトリ一覧のみです。ファイルのメタデータを確認してから読み取るかどうかを決めるには、fields: [name, type, size, path] を使用します。
• ファイルに対して get_file_contents を使用する前に、fields: [name, type, size, path] を指定して親ディレクトリを一覧表示します。ファイルが大きい場合や、ヘッダー／一部のセクションだけが必要な場合は、ファイル全体を取得するのではなく、HTTP の Range ヘッダーを使った生ファイル URLや、ほかに利用できる範囲指定読み取りツールなどで範囲を絞った抜粋を取得します。
• 古いサーバーでは、インストールされている MCP サーバーがその入力を公開している場合に、minimal_output: true を指定します（最小限の出力にすると、head／base などの大きなペイロードを含む必須でないネストされたフィールドが削除されます）。
• mcp list-tools または使用するサーバーバージョンのツールドキュメントで、メソッドのスキーマを確認し、パラメーターがサポートされていることを確かめます。

アクションのツールセット

• list_workflows - GitHub Actions のワークフローを一覧表示します
• list_workflow_runs - ワークフローの実行を一覧表示します
• get_workflow_run - 特定のワークフロー実行の詳細を取得します
• download_workflow_run_artifact - ワークフローのアーティファクトをダウンロードします

コードセキュリティのツールセット

• list_code_scanning_alerts - コードスキャンアラートを一覧表示します
• get_code_scanning_alert - 特定のアラートの詳細を取得します
• create_code_scanning_alert - コードスキャンアラートを作成します

ワークフローのプロンプト／テンプレートから list_code_scanning_alerts を呼び出す場合は、応答サイズを制限し、過大なペイロードを避けるため、常に state: open と severity: critical,high を含めます。

ディスカッションのツールセット

• list_discussions - リポジトリ内のディスカッションを一覧表示します
• create_discussion - 新しいディスカッションを作成します

ラベルのツールセット

• get_label - ラベルの詳細を取得します
• list_labels - リポジトリ内のラベルを一覧表示します
• create_label - 新しいラベルを作成します

ユーザーのツールセット

• get_me - ⚠️ 非推奨 — インテグレーショントークンでは HTTP 403 が返されます。自分の識別情報（actor、repository、run_id など）を確認するには、各プロンプトの冒頭に提供される <github-context> ブロックを使用してください。
• get_user - ユーザープロフィール情報を取得します
• list_users - ユーザーを一覧表示します

通知のツールセット

• list_notifications - ユーザーの通知を一覧表示します
• mark_notifications_read - 通知を既読にします

組織のツールセット

• get_organization - 組織の詳細を取得します
• list_organizations - 組織を一覧表示します

Gist のツールセット

• create_gist - 新しい gist を作成します
• list_gists - ユーザーの gist を一覧表示します

認証の詳細

リモートモードの認証

リモートモードでは Bearer トークン認証を使用します。

ヘッダー：

• Authorization: Bearer <token> - 認証に必須です
• X-MCP-Readonly: true - 任意。読み取り専用モードを有効にします

トークンのソース：

• デフォルト：${{ secrets.GH_AW_GITHUB_TOKEN }} または ${{ secrets.GITHUB_TOKEN }}
• カスタム：github-token フィールドで設定します

ローカルモードの認証

ローカルモードでは環境変数を使用します。

環境変数：

• GITHUB_PERSONAL_ACCESS_TOKEN - 認証に必須です
• GITHUB_READ_ONLY=1 - 任意。読み取り専用モードを有効にします
• GITHUB_TOOLSETS=<comma-separated-list> - 任意。有効にするツールセットを指定します

ベストプラクティス

ツールセットの選択

1. デフォルトから始める：ほとんどのワークフローでは、推奨されるデフォルトのツールセットで十分な機能を利用できます
2. 特定のツールセットを有効にする：特定の機能が必要な場合にのみ、追加のツールセットを有効にします
3. セキュリティ上の考慮事項：書き込み操作に注意し、可能な場合は読み取り専用モードの使用を検討してください
4. パフォーマンス：使用するツールセットを減らすと、初期化時間とメモリ使用量を削減できます

トークンの権限

有効にするツールセットに対して、GitHub トークンに適切な権限があることを確認してください。

• repos ツールセット：リポジトリの読み取り／書き込み権限が必要です
• issues ツールセット：Issue の読み取り／書き込み権限が必要です
• pull_requests ツールセット：プルリクエストの読み取り／書き込み権限が必要です
• actions ツールセット：アクションの読み取り／書き込み権限が必要です
• discussions ツールセット：ディスカッションの読み取り／書き込み権限が必要です

リモートモードとローカルモード

リモートモードを使用する場合：

• 初期化を速くしたい場合（起動する Docker コンテナーがありません）
• インターネットにアクセスできる GitHub Actions 環境で実行している場合
• Docker イメージタグを指定せずに最新バージョンを使用したい場合

ローカルモードを使用する場合：

• MCP サーバーの特定のバージョンが必要な場合
• カスタム引数を使用したい場合
• インターネットにアクセスできない環境で実行している場合
• MCP サーバーのローカルビルドでテストしたい場合

Allowed から Toolsets への移行

allowed: パターンを使用する既存のワークフローがある場合は、保守性と安定性を高めるため、toolsets: への移行をお勧めします。個々のツール名は MCP サーバーのバージョン間で変更される場合がありますが、ツールセットはワークフローが壊れない安定した API を提供します。

移行例

allowed: を使用（非推奨）：

tools:
  github:
    allowed:
      - get_repository
      - get_file_contents
      - list_commits
      - list_issues
      - create_issue
      - update_issue

toolsets: を使用（推奨）：

tools:
  github:
    toolsets: [repos, issues]

ツールとツールセットの対応表

必要なツールがどのツールセットに含まれているかを確認するには、この表を使用してください。

allowed: のツール	toolsets: への移行先
get_me ⚠️（非推奨 — 403 を返します。代わりに <github-context> を使用してください）	users
get_teams、get_team_members	context
get_repository、get_file_contents、search_code、list_commits	repos
issue_read、list_issues、create_issue、update_issue、search_issues	issues
pull_request_read、list_pull_requests、create_pull_request	pull_requests
list_workflows、list_workflow_runs、get_workflow_run	actions
list_code_scanning_alerts ⚠️（常に state: open と severity: critical,high を含めてください）、get_code_scanning_alert	code_security
list_discussions、create_discussion	discussions
get_label、list_labels、create_label	labels
get_user、list_users	users
repos／issues／PR のツールの組み合わせ	[default]
すべてのツール	[all]

移行の手順

1. 使用中のツールを特定する：現在の allowed: リストを確認します
2. ツールセットに対応付ける：上の表を使って対応するツールセットを確認します
3. 設定を置き換える：allowed: を toolsets: に変更します
4. テストする：gh aw mcp inspect <workflow> を実行し、ツールを利用できることを確認します
5. コンパイルする：gh aw compile を実行してロックファイルを更新します

カスタム MCP サーバーでの Allowed パターンの使用

:::note[Allowed を使用する場合] allowed: パターンが適しているのは、次の場合です。

• カスタム MCP サーバー（GitHub 以外）
• 既存のワークフローを段階的に移行する場合
• ツールセット内の特定のツールをきめ細かく制限する場合

GitHub ツールでは、常に allowed: ではなく toolsets: を使用してください。 :::

カスタム MCP サーバーのツールを制限するには、引き続き allowed: フィールドを使用できます。

mcp-servers:
  notion:
    container: "mcp/notion"
    allowed: ["search_pages", "get_page"]  # Fine for custom MCP servers

GitHub ツールでは、アクセスをさらに制限するために allowed: を toolsets: と組み合わせることもできますが、新しいワークフローではこのパターンをお勧めしません。

GitHub API の制限

GitHub MCP サーバーまたは GitHub REST API からアクセスできない GitHub データもあります。実行時にエラーが表面化しなかったり、不完全な結果になったりするのを避けるため、ワークフローを設計する際は以下の制限に注意してください。

請求とコストのデータ

❌ 標準の API 権限では利用できません：

• 実行ごとの詳細なコストデータ — GitHub Actions は、ワークフロー実行ごとの請求コストを REST API 経由では公開していません。特定のワークフロー実行の正確なコストを取得するエンドポイントはありません。
• Actions の請求概要 — 請求エンドポイント（例：/orgs/{org}/settings/billing/actions）には admin:org スコープが必要ですが、actions:read やデフォルトの GITHUB_TOKEN には付与されていません。

⚠️ 請求やコストに関するワークフローを提案する際は、必ず次の点を明記してください：

GitHub Actions の詳細な請求・コストデータは、actions:read 権限で標準の GitHub API を通じて取得できません。実行ごとのコストデータや請求概要の取得を試みるワークフローは、admin:org スコープの個人アクセストークンが明示的に設定されていない限り、エラーが表面化しないまま失敗するか、空の結果を返します。

✅ コストレポートの代替手段：

1. GitHub Actions の使用状況レポート — GitHub の請求 UI（Settings → Billing → Usage）から使用状況レポートをダウンロードするか、請求 CSV エクスポートエンドポイントから取得します（PAT で admin:org スコープが必要です）。
2. 請求設定 UI — 手動でコストデータを確認できるよう、個人アカウントの場合は https://github.com/organizations/{org}/settings/billing または https://github.com/settings/billing に案内します。
3. ワークフロー実行メタデータ — list_workflow_runs と get_workflow_run（actions ツールセットから利用可能）を使用して、実行時間、ステータス、タイミングを取得できます。ただし、金額は取得できません。
4. サードパーティのコスト追跡 — 事前承認済みの API アクセスを使用するサードパーティの CI コストツールと連携します。

組織をまたぐデータアクセス

❌ 明示的な認可がない場合は利用できません：

• ワークフローがアクセスできるのは、設定された GitHub トークンにアクセス権が付与されているリポジトリおよび組織のデータのみです。
• 組織をまたいだリポジトリの読み取りには、対象の組織へのアクセス権を持つ PAT または GitHub App トークンが必要です。デフォルトの GITHUB_TOKEN のスコープは、現在のリポジトリが属する組織に限られます。
• 他の組織のメンバーシップやチームのデータには、その組織に対する明示的な read:org 権限がなければアクセスできません。

組織のメンバーシップとプライベートデータ

❌ 追加のスコープが必要です：

• 組織メンバーの一覧 — プライベートな組織メンバーシップを読み取るには read:org スコープが必要です。デフォルトの GITHUB_TOKEN で参照できるのは公開メンバーシップのみです。
• プライベートリポジトリのコンテンツ — トークンに明示的なリポジトリへのアクセス権がある場合にのみ利用できます。
• シークレットの値 — GitHub Secrets は API 経由では書き込み専用です。作成後に値を読み戻すことはできません。

レート制限

⚠️ API のレート制限に注意してください：

• GitHub REST API にはレート制限があります（PAT を使用した認証済みリクエストでは通常 1 時間あたり 5,000 件、GITHUB_TOKEN ではそれより少なくなります）。
• 大量のデータを収集するワークフロー（例：多数のリポジトリにわたるすべてのワークフロー実行の一覧表示）では、レート制限に達する可能性があります。慎重にページネーションを行い、不要なリクエストを避けるようワークフローを設計してください。
• GraphQL API には、クエリの複雑さに基づく別のレート制限があります。

トラブルシューティング

よくある問題

問題：ツールが見つからない、または利用できない

• 解決策：allowed: を使ってツールを制限していないか確認してください。関連するすべてのツールを利用するには、代わりに toolsets: を使用してください。
• 確認方法：gh aw mcp inspect <workflow-name> を実行して、実際に利用可能なツールを確認してください。

問題：ツールセットを指定した後、機能が不足している

• 原因：必要なツールがすべて含まれていない、範囲が狭すぎるツールセットを使用しています
• 解決策：追加のツールセット（例：toolsets: [default, actions]）を追加するか、すべての機能にアクセスするために [all] を使用してください

問題：allowed: リストを使用しているワークフローが冗長で、メンテナンスしにくい

• 解決策：上記の移行ガイドに従って、toolsets: 設定に移行してください

デバッグのベストプラクティス

1. まず [default] ツールセットを使用する：ほとんどのワークフローはデフォルトのツールセットで問題なく動作します
2. 必要に応じて特定のツールセットを追加する：actions、discussions などのツールセットを段階的に追加してください
3. gh aw mcp inspect を使用する：実際に利用可能なツールを確認してください
4. ツールとツールセットの対応関係を確認する：上記の表を参照して、適切なツールセットを確認してください

参考資料

• GitHub MCP サーバーリポジトリ
• Model Context Protocol 仕様
• GitHub Actions ドキュメント