GitHub MCP server
✓ 인증됨AI 클라이언트가 GitHub REST API와 상호작용하여 repository, issue, pull request를 관리할 수 있도록 합니다.
다른 이름 jaimenbell/github-mcp, jaimenbell-github-mcp
- 스타
- 0
- Tools
- 14
- 다운로드, 30일
- 77
- 최신 버전
- 0.1.1
- 마지막 커밋
- 2026년 8월 12일
- 라이선스
- MIT
GitHub MCP란?
GitHub은(는) MCP server입니다. AI 클라이언트가 GitHub REST API와 상호작용하여 repository, issue, pull request를 관리할 수 있도록 합니다. 14개 도구를 제공합니다. 예: get_repo, list_issues, get_issue.
프로젝트 README에서 생성된 요약
GitHub MCP server 정보
이 server는 AI 클라이언트에서 GitHub repository와 issue를 직접 관리할 수 있는 기능을 제공합니다. GitHub REST API와의 가교 역할을 수행하여 사용자가 repository 메타데이터를 가져오고, issue 목록을 확인하며, 공개 repository를 검색하고, 파일 내용을 읽을 수 있도록 지원합니다. Claude Desktop과 같은 도구를 사용하여 repository 관리를 로컬 AI 워크플로우에 통합하려는 개발자를 위해 설계되었습니다.
이 server는 쓰기 기능이 기본적으로 비활성화된 엄격한 보안 모델로 작동합니다. get_repo 및 list_pull_requests와 같은 읽기 도구는 GitHub의 표준 rate limit 내에서 인증 없이 작동하지만, 모든 수정 도구는 세분화된 personal access token과 GITHUB_MCP_ENABLE_WRITE 환경 변수의 명시적 설정이 필요합니다. 이를 통해 사용자가 의도적으로 환경을 구성하지 않는 한 AI가 실수로 코드나 issue를 수정하는 것을 방지합니다.
이 구현체는 REST v1 API에 초점을 맞추고 있으며, rate limit 및 네트워크 오류에 대한 특화된 에러 핸들링을 포함합니다. 쓰기 그룹이 활성화되면 create_issue, comment_on_issue, add_labels를 포함한 14개의 특정 도구를 사용하여 능동적인 repository 유지보수를 수행할 수 있습니다.
활용 사례
- 1repository 메타데이터 감사AI에게 star 수, license, default branch와 같은 repository 상세 정보를 조회하도록 요청합니다.
- 2pull request 검토AI가 특정 pull request 목록을 가져오고 최근 변경 사항을 요약하도록 합니다.
- 3코드베이스 내용 조사AI에게 repository 내 특정 파일의 내용을 읽도록 요청합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
GitHub MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 GitHub MCP 설치
$ claude mcp add github-mcp -- uvx jaimenbell-github-mcpCursor에 GitHub MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"github-mcp": {
"command": "uvx",
"args": [
"jaimenbell-github-mcp"
]
}
}
}VS Code에 GitHub MCP 설치
.vscode/mcp.json
{
"servers": {
"github-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"jaimenbell-github-mcp"
]
}
}
}VS Code CLI에 GitHub MCP 설치
$ code --add-mcp '{"name":"github-mcp","type":"stdio","command":"uvx","args":["jaimenbell-github-mcp"]}'Claude Desktop에 GitHub MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"github-mcp": {
"command": "uvx",
"args": [
"jaimenbell-github-mcp"
]
}
}
}Codex에 GitHub MCP 설치
$ codex mcp add github-mcp -- uvx jaimenbell-github-mcpCodex config.toml에 GitHub MCP 설치
~/.codex/config.toml
[mcp_servers.github-mcp] command = "uvx" args = ["jaimenbell-github-mcp"]
Gemini CLI에 GitHub MCP 설치
$ gemini mcp add -s user github-mcp uvx -- jaimenbell-github-mcpGemini settings.json에 GitHub MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"github-mcp": {
"command": "uvx",
"args": [
"jaimenbell-github-mcp"
]
}
}
}GitHub MCP 도구 14
README에서 감지됨get_repolist_issuesget_issuelist_pull_requestsget_pull_requestget_file_contentsearch_reposget_userlist_commitscreate_issuecomment_on_issueupdate_issue_state
| get_repo | — | |
| list_issues | — | |
| get_issue | — | |
| list_pull_requests | — | |
| get_pull_request | — | |
| get_file_content | — | |
| search_repos | — | |
| get_user | — | |
| list_commits | — | |
| create_issue | — | |
| comment_on_issue | — | |
| update_issue_state | — |
도구 14개 모두 보기도구 수 줄이기
add_labelscreate_pr_review_comment
| add_labels | — | |
| create_pr_review_comment | — |
구성
GITHUB_MCP_ENABLE_WRITEGITHUB_MCP_LIVEGITHUB_TOKEN
| 이름 | 설명 | 유형 |
|---|---|---|
| GITHUB_MCP_ENABLE_WRITE | — | |
| GITHUB_MCP_LIVE | — | |
| GITHUB_TOKEN | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능jaimenbell/github-mcp is public and reachablegithub.com/jaimenbell/github-mcp ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)No build attestation published for this release검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-08-12github.com/jaimenbell/github-mcp ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from jaimenbell-github-mcp통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음69 resolved dependencies checked; no critical advisoryosv.dev ↗통과
- 모델에 대한 숨겨진 지침 없음14 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기github-mcp
A public read+write MCP server over the GitHub REST API, built to the desktop-mcp/rag-mcp/mcp-factory standard (own pyproject, fastmcp server, honest README, real test suite) with env-gated tool groups (write disabled by default). Not the official GitHub MCP server -- see below.
Quickstart (60 seconds)
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"
}
}
}
The write tool group (issue/PR mutations) is off by default -- see
Env vars below to enable it.
What this is / is not
This is a reference portfolio implementation demonstrating a hardened read+write MCP server pattern over a real external SaaS API (GitHub) -- env-gated tool groups, typed error/rate-limit handling, auth that degrades gracefully, a real test suite. It exists to show, concretely, "I build read/write MCP servers over external APIs" with a link a client can click.
It is NOT the official GitHub MCP server. It does not aim for parity
with GitHub's own MCP offering (GraphQL, Actions, webhooks, GitHub Apps are
all out of scope -- see below). It started life as a factory-scaffolded
read-only demo (mcp-factory's
generated/github_read_server.py) and was hand-hardened into this
standalone read+write server -- the scaffold-then-harden path is itself part
of the story this repo tells.
Tools (14)
One row per tool -- the two groups below just control default-on/off state, not what exists.
| Tool | Group | What it does |
|---|---|---|
get_repo |
read |
Repo metadata (stars, language, license, default branch, archived flag...) |
list_issues |
read |
List issues on a repo (PRs filtered out) |
get_issue |
read |
Fetch a single issue |
list_pull_requests |
read |
List pull requests on a repo |
get_pull_request |
read |
Fetch a single pull request |
get_file_content |
read |
Read a repo file's content (base64-decoded, binary detected not decoded) |
search_repos |
read |
Search public repositories |
get_user |
read |
Public user/org profile |
list_commits |
read |
List commits on a branch/ref |
create_issue |
write |
Open an issue |
comment_on_issue |
write |
Comment on an issue/PR |
update_issue_state |
write |
Open/close an issue |
add_labels |
write |
Add labels to an issue/PR |
create_pr_review_comment |
write |
Create a PR review comment on a diff line |
read is always on and works unauthenticated (GitHub's 60 req/hr tier).
write is env-gated and OFF by default -- requires
GITHUB_MCP_ENABLE_WRITE=1 and GITHUB_TOKEN.
A disabled write call returns a structured policy_refusal error (never a
silent no-op, never a crash). A write call with the group enabled but no
token returns a structured auth_required error -- the group gate and the
token precondition are checked independently, both before any network call.
Write-safety-off-by-default
This is defense-in-depth, mirroring desktop-mcp's input group: harness-level
permission prompts are the first gate, but the server itself refuses every
write tool unless its own environment explicitly opts in with
GITHUB_MCP_ENABLE_WRITE=1, and even then refuses without a GITHUB_TOKEN.
A misconfigured or overly-permissive MCP host cannot turn on GitHub mutations
this process wasn't deliberately configured to allow. The registration this
repo ships with (see ~/.claude.json's github-mcp entry) has the write
group absent from env -- enabling it is a deliberate per-registration
operator choice, not a code change.
Honest-capabilities table
Every claim below maps to the file that implements it and the test(s) that verify it -- no capability is asserted without a corresponding implementation and test.
| Claim | Implementation | Verified by |
|---|---|---|
| Repo metadata (stars, language, license, default branch, archived flag...) | github_mcp/groups/read.py::get_repo |
tests/test_read.py::TestGetRepo, live: tests/test_live_smoke.py::test_live_get_repo_real_json |
| List / fetch issues (PRs filtered from list) | github_mcp/groups/read.py::list_issues, get_issue |
tests/test_read.py::TestListIssues, TestGetIssue |
| List / fetch pull requests | github_mcp/groups/read.py::list_pull_requests, get_pull_request |
tests/test_read.py::TestListPullRequests, TestGetPullRequest |
| Read a repo file's content (base64-decoded, binary detected not decoded) | github_mcp/groups/read.py::get_file_content |
tests/test_read.py::TestGetFileContent |
| Search public repositories | github_mcp/groups/read.py::search_repos |
tests/test_read.py::TestSearchRepos |
| Public user/org profile | github_mcp/groups/read.py::get_user |
tests/test_read.py::TestGetUser |
| List commits on a branch/ref | github_mcp/groups/read.py::list_commits |
tests/test_read.py::TestListCommits |
| Open an issue | github_mcp/groups/write.py::create_issue |
tests/test_write.py::TestCreateIssue |
| Comment on an issue/PR | github_mcp/groups/write.py::comment_on_issue |
tests/test_write.py::TestCommentOnIssue |
| Open/close an issue | github_mcp/groups/write.py::update_issue_state |
tests/test_write.py::TestUpdateIssueState |
| Add labels to an issue/PR | github_mcp/groups/write.py::add_labels |
tests/test_write.py::TestAddLabels |
| Create a PR review comment on a diff line | github_mcp/groups/write.py::create_pr_review_comment |
tests/test_write.py::TestCreatePrReviewComment |
| Write group OFF by default, structured refusal when disabled | github_mcp/config.py::group_enabled, gated_write |
tests/test_config.py::TestGroupEnabled, tests/test_write.py::TestGateDisabledByDefault |
| Write tools require a token even when the group is enabled | github_mcp/config.py::check_write_preconditions |
tests/test_config.py::TestCheckWritePreconditions, tests/test_write.py::TestAuthRequiredWhenGroupEnabled |
| Fine-grained PAT auth, degrades to unauthenticated tier when absent | github_mcp/client.py::_headers |
tests/test_client.py::TestAuthHeaderInjection, tests/test_read.py::TestUnauthDegrade |
GitHub primary rate-limit (403 + X-RateLimit-Reset) and secondary rate-limit (403 + Retry-After, no X-RateLimit-Remaining) both surface as a typed error with reset/retry time, never a crash |
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 |
Malformed owner/repo/path (control chars etc.) that would raise httpx.InvalidURL surfaces as a typed error, never an uncaught exception |
github_mcp/client.py::request |
tests/test_client.py::TestNetworkError::test_malformed_path_raises_invalid_url_caught_as_network_error |
| Generic 4xx/5xx surfaces as a typed error, never a crash | github_mcp/client.py::_api_error |
tests/test_client.py::TestApiError |
| Non-JSON / malformed responses and network failures surface as typed errors | github_mcp/client.py::_handle_response, request |
tests/test_client.py::TestDecodeError, TestNetworkError |
Limitations (read before relying on this)
- REST v1 only. No GraphQL API coverage.
- No webhooks / GitHub App auth. Fine-grained PAT only.
- No Actions/workflow-dispatch tools. Issue/PR CRUD is the v1 write surface.
- Unauthenticated read is rate-limited to 60 req/hr by GitHub itself (10
req/min for search) -- expect
rate_limitederrors under sustained unauthenticated use; setGITHUB_TOKEN(even a read-only fine-grained PAT) to raise this considerably. get_file_contenttruncates past 100KB and reports (rather than decodes) non-UTF-8 files.- No pagination beyond a single page for list endpoints (
limit, capped per-endpoint, is the only page-size control in v1). - Not registered with the mcp-factory hub. Ships as a standalone repo (own pyproject, system Python312 install), matching the rag-mcp/desktop-mcp model.
Env vars
| Var | Effect | Default |
|---|---|---|
GITHUB_MCP_ENABLE_WRITE |
enable the write tool group |
unset (off) |
GITHUB_TOKEN |
fine-grained PAT; read works without it (degraded unauth rate), write requires it | unset |
GITHUB_MCP_LIVE |
1 to run the real-network smoke test (see Testing) |
unset (skip) |
Usage examples
// 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", ...}}
Testing
CI (.github/workflows/ci.yml) runs this suite on every push/PR and fails
the build if the Tests badge above drifts from what the suite actually
reports -- see 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
Install
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
Setup / connect
pip install -r requirements.txton Python 3.12+.- (Optional) generate a fine-grained PAT scoped to the repos you want read+write access to (Issues: read/write, Pull requests: read/write, Contents: read is enough for v1). Read tools work with no token at all -- they just run at GitHub's unauthenticated 60 req/hr tier.
- Add to your MCP host config (e.g.
~/.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.
}
}
}
}
- To enable write tools for a given deployment, add
"GITHUB_MCP_ENABLE_WRITE": "1"to that entry'senvblock. This is a registration-time operator decision, not a code change.
Registered in ~/.claude.json as github-mcp (stdio, system Python312,
read group always on, write group absent from env -- off).
Commercial support
Maintained by Jaimen Bell. For production MCP integrations, custom servers, or agent-reliability work, see jaimenbell.dev.
Building your own MCP server? The MCP Starter Kit has templates, a build playbook, and packaging war-stories from shipping this one.
mcp-name: io.github.jaimenbell/github-mcp
GitHub MCP 질문
GitHub MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add github-mcp -- uvx jaimenbell-github-mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
GitHub MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
GitHub MCP는 어떤 도구를 제공하나요?
14개 도구를 제공합니다. 예: get_repo, list_issues, get_issue, list_pull_requests, get_pull_request.
이 server는 기본적으로 GitHub 쓰기 작업을 지원합니까?
아니요, 안전을 위해 쓰기 작업은 기본적으로 비활성화되어 있습니다. GITHUB_MCP_ENABLE_WRITE 환경 변수를 1로 설정하여 명시적으로 활성화해야 합니다.
repository 데이터를 읽기 위해 GitHub token이 필요합니까?
아니요, 읽기 도구는 GitHub의 인증되지 않은 티어를 사용하여 인증 없이 작동합니다. 다만 시간당 60회 요청으로 제한되는 낮은 rate limit이 적용됩니다.
쓰기 기능을 활성화하지 않거나 token을 제공하지 않고 쓰기 도구를 사용하면 어떻게 됩니까?
server는 구조화된 에러를 반환합니다. 쓰기 그룹이 비활성화된 경우 policy_refusal 에러가 발생하며, 그룹은 활성화되었으나 token이 제공되지 않은 경우 auth_required 에러가 발생합니다.