github-mcp

github-mcp

GitHub REST APIを介した、公開読み書き対応MCP サーバーです。 desktop-mcp/rag-mcp/mcp-factoryの標準（独自の pyproject、fastmcpサーバー、誠実なREADME、実際のテストスイート）に準拠し、環境変数で有効化する ツールグループを備えています（書き込みはデフォルトで無効）。GitHub公式のMCP サーバーではありません。詳しくは以下をご覧ください。

クイックスタート（60秒）

pip install jaimenbell-github-mcp

// Add to your MCP host config (e.g. Claude Desktop/Code's mcpServers block)
{
  "mcpServers": {
    "github-mcp": {
      "command": "github-mcp"
    }
  }
}

writeツールグループ（issue／PRの変更）はデフォルトで無効です。有効にする方法は、 以下の環境変数をご覧ください。

これは何か／何ではないか

これは、実際の外部SaaS API（GitHub）を介した、堅牢な読み書き対応MCP サーバーの パターンを示すリファレンス実装です。環境変数で有効化するツールグループ、型付きのエラー／レート制限処理、 適切に機能を縮退する認証、実際のテストスイートを備えています。「外部APIを介した読み書き対応MCP サーバーを構築する」という実績を、クライアントがクリックして確認できるリンクとともに、具体的に示すことを目的としています。

GitHub公式のMCP サーバーではありません。 GitHub独自のMCP製品との同等性を目指すものではありません（GraphQL、Actions、webhook、GitHub Appsはすべて対象外です。詳しくは以下をご覧ください）。当初はmcp-factoryの generated/github_read_server.pyで生成した、読み取り専用のデモとして始まり、手作業で堅牢化して、単独の読み書き対応サーバーに仕上げました。スキャフォールドしてから堅牢化するという道筋も、このリポジトリが伝えるストーリーの一部です。

ツール（14）

各行が1つのツールです。以下の2つのグループは、デフォルトで有効か無効かを制御するだけで、 ツールの有無を制御するものではありません。

ツール	グループ	機能
get_repo	read	リポジトリのメタデータ（スター数、言語、ライセンス、デフォルトブランチ、アーカイブ済みフラグなど）
list_issues	read	リポジトリのissue一覧（PRは除外）
get_issue	read	1件のissueを取得
list_pull_requests	read	リポジトリのプルリクエスト一覧
get_pull_request	read	1件のプルリクエストを取得
get_file_content	read	リポジトリ内のファイルの内容を読み取る（Base64をデコード。バイナリは検出するがデコードしない）
search_repos	read	公開リポジトリを検索
get_user	read	公開ユーザー／組織のプロフィール
list_commits	read	ブランチ／参照先のコミット一覧
create_issue	write	issueを作成
comment_on_issue	write	issue／PRにコメント
update_issue_state	write	issueをオープン／クローズ
add_labels	write	issue／PRにラベルを追加
create_pr_review_comment	write	差分行にPRレビューコメントを作成

readは常に有効で、認証なしでも動作します（GitHubの60リクエスト／時の利用枠）。 writeは環境変数で有効化する必要があり、デフォルトでは無効です。有効にするには、 GITHUB_MCP_ENABLE_WRITE=1とGITHUB_TOKENの両方が必要です。

無効な状態でwriteを呼び出すと、構造化されたpolicy_refusalエラーが返されます（何もせずに処理を終えることも、クラッシュすることもありません）。グループが有効でもトークンがない状態でwriteを呼び出すと、構造化されたauth_requiredエラーが返されます。グループの有効化とトークンの前提条件は個別に確認され、どちらもネットワーク呼び出しの前にチェックされます。

書き込みはデフォルトで無効

これは多層防御の考え方で、desktop-mcp の input グループを反映しています。ハーネスレベルの許可プロンプトが最初の関門ですが、サーバー自体も、環境変数で GITHUB_MCP_ENABLE_WRITE=1 が明示的に設定されていない限り、すべての書き込みツールを拒否します。また、設定されていても GITHUB_TOKEN がなければ拒否します。設定ミスのある、または過度に寛容な MCP ホストであっても、このプロセスで意図的に許可するよう設定されていない GitHub の変更を有効にすることはできません。このリポジトリが提供する登録設定（~/.claude.json の github-mcp エントリを参照）では、書き込みグループは環境変数に含まれていません。有効化はコード変更ではなく、登録ごとにオペレーターが意図して選択するものです。

実装・検証済み機能の一覧

以下の各主張は、実装しているファイルと検証するテストに対応しています。対応する実装とテストがない機能は主張していません。

主張	実装	検証
リポジトリのメタデータ（スター数、言語、ライセンス、デフォルトブランチ、アーカイブ済みフラグなど）	github_mcp/groups/read.py::get_repo	tests/test_read.py::TestGetRepo、実環境：tests/test_live_smoke.py::test_live_get_repo_real_json
イシューの一覧表示／取得（一覧からはPRを除外）	github_mcp/groups/read.py::list_issues、get_issue	tests/test_read.py::TestListIssues、TestGetIssue
プルリクエストの一覧表示／取得	github_mcp/groups/read.py::list_pull_requests、get_pull_request	tests/test_read.py::TestListPullRequests、TestGetPullRequest
リポジトリファイルの内容を読み取る（Base64をデコードし、バイナリは検出するがデコードしない）	github_mcp/groups/read.py::get_file_content	tests/test_read.py::TestGetFileContent
公開リポジトリを検索する	github_mcp/groups/read.py::search_repos	tests/test_read.py::TestSearchRepos
公開ユーザー／組織のプロフィール	github_mcp/groups/read.py::get_user	tests/test_read.py::TestGetUser
ブランチ／参照上のコミットを一覧表示する	github_mcp/groups/read.py::list_commits	tests/test_read.py::TestListCommits
イシューを作成する	github_mcp/groups/write.py::create_issue	tests/test_write.py::TestCreateIssue
イシュー／PRにコメントする	github_mcp/groups/write.py::comment_on_issue	tests/test_write.py::TestCommentOnIssue
イシューをオープン／クローズする	github_mcp/groups/write.py::update_issue_state	tests/test_write.py::TestUpdateIssueState
イシュー／PRにラベルを追加する	github_mcp/groups/write.py::add_labels	tests/test_write.py::TestAddLabels
差分の行にPRレビューコメントを作成する	github_mcp/groups/write.py::create_pr_review_comment	tests/test_write.py::TestCreatePrReviewComment
書き込みグループはデフォルトで無効で、無効時は構造化された拒否を返す	github_mcp/config.py::group_enabled、gated_write	tests/test_config.py::TestGroupEnabled、tests/test_write.py::TestGateDisabledByDefault
グループが有効でも、書き込みツールにはトークンが必要	github_mcp/config.py::check_write_preconditions	tests/test_config.py::TestCheckWritePreconditions、tests/test_write.py::TestAuthRequiredWhenGroupEnabled
粒度の細かいPAT認証。トークンがない場合は未認証のティアにフォールバックする	github_mcp/client.py::_headers	tests/test_client.py::TestAuthHeaderInjection、tests/test_read.py::TestUnauthDegrade
GitHubのプライマリレート制限（403 + X-RateLimit-Reset）とセカンダリレート制限（403 + Retry-After、X-RateLimit-Remainingなし）は、どちらもリセット／再試行時刻を含む型付きエラーとして通知され、クラッシュしない	github_mcp/client.py::_rate_limit_error、_is_rate_limit_response	tests/test_client.py::TestRateLimitError、tests/test_client.py::TestRateLimitError::test_secondary_rate_limit_no_ratelimit_headers_retry_after_only、tests/test_read.py::TestUnauthDegrade::test_get_repo_rate_limited_without_token_is_typed
httpx.InvalidURLを発生させる不正なowner/repo/path（制御文字など）は、捕捉されない例外ではなく型付きエラーとして通知される	github_mcp/client.py::request	tests/test_client.py::TestNetworkError::test_malformed_path_raises_invalid_url_caught_as_network_error
汎用の4xx／5xxはクラッシュせず、型付きエラーとして通知される	github_mcp/client.py::_api_error	tests/test_client.py::TestApiError
JSON以外／不正なレスポンスおよびネットワーク障害は、型付きエラーとして通知される	github_mcp/client.py::_handle_response、request	tests/test_client.py::TestDecodeError、TestNetworkError

制限事項（利用前にお読みください）

• REST v1 のみです。 GraphQL API には対応していません。
• Webhook／GitHub App 認証には対応していません。 使用できるのは細粒度 PAT のみです。
• Actions／workflow-dispatch ツールはありません。 v1 で書き込み可能なのは Issue／PR の CRUD のみです。
• 認証なしの読み取りは、GitHub 自体によって 60 req/hr に制限されます（検索は 10 req/min）。認証なしで継続的に使用すると rate_limited エラーが発生することがあります。上限を大幅に引き上げるには、GITHUB_TOKEN（読み取り専用の細粒度 PAT でも可）を設定してください。
• get_file_content は 100KB を超えると内容を切り詰め、UTF-8 以外のファイルはデコードせず、その旨を報告します。
• リストエンドポイントでは1 ページを超えるページネーションに対応していません（v1 でページサイズを制御できるのは limit のみで、エンドポイントごとに上限があります）。
• mcp-factory ハブには登録されていません。 独立したリポジトリとして提供されます（独自の pyproject、システム Python312 へのインストール）。rag-mcp／desktop-mcp と同じモデルです。

環境変数

変数	効果	デフォルト
GITHUB_MCP_ENABLE_WRITE	write ツールグループを有効にする	未設定（オフ）
GITHUB_TOKEN	細粒度 PAT。読み取りは未設定でも動作します（認証なしの制限されたレート）。書き込みには必須です	未設定
GITHUB_MCP_LIVE	実際のネットワークを使ったスモークテストを実行するには 1 を設定します（「テスト」を参照）	未設定（スキップ）

使用例

// A tool call from the MCP host, illustrative -- not a shell command.
{"tool": "get_repo", "arguments": {"owner": "anthropics", "repo": "anthropic-sdk-python"}}
// -> {"ok": true, "full_name": "anthropics/anthropic-sdk-python", "stargazers_count": 1234, ...}

// write group disabled (default):
{"tool": "create_issue", "arguments": {"owner": "o", "repo": "r", "title": "bug"}}
// -> {"ok": false, "error": {"type": "policy_refusal", "group": "write", "required_env": "GITHUB_MCP_ENABLE_WRITE", ...}}

// write group enabled, no token set:
{"tool": "create_issue", "arguments": {"owner": "o", "repo": "r", "title": "bug"}}
// -> {"ok": false, "error": {"type": "auth_required", "tool": "create_issue", ...}}

テスト

CI（.github/workflows/ci.yml）はプッシュ／PR のたびにこのテストスイートを実行し、テストバッジの表示が実際のテスト結果と異なる場合はビルドを失敗させます。詳しくは scripts/check_readme_counts.py を参照してください。

# unit suite (respx-mocked api.github.com, no real network touched)
python -m pytest -q

# handshake check -- prints every registered tool name
python scripts/list_tools.py

# real-network read smoke (get_repo against a stable public repo;
# no write smoke exists anywhere in this suite -- see safety rails above)
GITHUB_MCP_LIVE=1 python -m pytest -q -k live_get_repo

インストール

pip install -r requirements.txt   # or: pip install .
# deps: fastmcp==3.4.2, httpx==0.28.1
# test-only: pytest==9.0.3, respx==0.23.1

セットアップ／接続

1. Python 3.12 以降で pip install -r requirements.txt を実行します。
2. （任意）読み書きアクセスを許可するリポジトリを指定した細粒度 PATを生成します（Issues：読み取り／書き込み、Pull requests：読み取り／書き込み、Contents：読み取りで v1 には十分です）。読み取りツールはトークンなしでも動作します。その場合は、GitHub の認証なし向け 60 req/hr の制限が適用されます。
3. MCP ホストの設定（例：~/.claude.json）に追加します。

{
  "mcpServers": {
    "github-mcp": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
      "args": ["C:\\Users\\<you>\\projects\\github-mcp\\run_server.py"],
      "env": {
        "GITHUB_TOKEN": "your-fine-grained-pat-here"
        // GITHUB_MCP_ENABLE_WRITE intentionally absent -- write stays off
        // until you deliberately opt in per-deployment.
      }
    }
  }
}

4. 特定のデプロイで書き込みツールを有効にするには、そのエントリーの env ブロックに "GITHUB_MCP_ENABLE_WRITE": "1" を追加します。これは登録時にオペレーターが決定するものであり、コードの変更ではありません。

~/.claude.json には github-mcp として登録されています（stdio、システム Python312、read グループは常時有効、write グループは env に含まれず無効）。

商用サポート

Jaimen Bell が保守しています。本番環境向けの MCP 統合、カスタムサーバー、エージェントの信頼性に関する作業については、jaimenbell.dev をご覧ください。

独自の MCP サーバーを構築していますか？MCP Starter Kitには、テンプレート、構築ガイド、そしてこのサーバーをリリースする過程で得られたパッケージ化の実体験が収録されています。

mcp-name: io.github.jaimenbell/github-mcp