MCP server de GitHub
✓ VerificadoPermite que un cliente de IA interactúe con la API REST de GitHub para gestionar repositorios, issues y pull requests.
También conocido como jaimenbell/github-mcp, jaimenbell-github-mcp
- Stars
- 0
- Herramientas
- 14
- Descargas, 30 días
- 77
- Última versión
- 0.1.1
- Último commit
- 12 ago 2026
- Licencia
- MIT
¿Qué es GitHub MCP?
Permite que un cliente de IA interactúe con la API REST de GitHub para gestionar repositorios, issues y pull requests. Expone 14 herramientas, como get_repo, list_issues, get_issue.
Resumen generado a partir del README del proyecto
Acerca del MCP server de GitHub
Este servidor permite gestionar repositorios e issues de GitHub directamente desde un cliente de IA. Proporciona un puente hacia la API REST de GitHub, lo que permite a los usuarios obtener metadatos de repositorios, listar issues, buscar repositorios públicos y leer el contenido de archivos. Está diseñado para desarrolladores que desean integrar la gestión de repositorios en sus flujos de trabajo locales de IA utilizando herramientas como Claude Desktop.
El servidor opera con un modelo de seguridad estricto en el que las capacidades de escritura están desactivadas por defecto. Mientras que las herramientas de lectura como get_repo y list_pull_requests funcionan sin autenticación bajo los límites de tasa estándar de GitHub, cualquier herramienta de mutación requiere un token de acceso personal con permisos granulares y la configuración explícita de la variable de entorno GITHUB_MCP_ENABLE_WRITE. Esto garantiza que una IA no pueda modificar accidentalmente tu código o tus issues a menos que hayas configurado deliberadamente el entorno para permitirlo.
Esta implementación se centra en la API REST v1 e incluye un manejo de errores especializado para límites de tasa y fallos de red. Ofrece catorce herramientas específicas, incluyendo create_issue, comment_on_issue y add_labels, para facilitar el mantenimiento activo del repositorio una vez que se habilita el grupo de escritura.
Qué puedes hacer con él
- 1Auditar metadatos de repositoriosPide a la IA que recupere detalles sobre un repositorio, como su número de estrellas, licencia y rama por defecto.
- 2Revisar pull requestsHaz que la IA liste y obtenga pull requests específicos para resumir los cambios recientes.
- 3Examinar el contenido del códigoSolicita a la IA que lea el contenido de un archivo específico dentro de un repositorio.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Cómo instalar GitHub MCP
Formatos verificados el 10 nov 2026Añadir a CursorAñadir a GooseInstalar GitHub MCP en Claude Code
$ claude mcp add github-mcp -- uvx jaimenbell-github-mcpInstalar GitHub MCP en Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"github-mcp": {
"command": "uvx",
"args": [
"jaimenbell-github-mcp"
]
}
}
}Instalar GitHub MCP en VS Code
.vscode/mcp.json
{
"servers": {
"github-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"jaimenbell-github-mcp"
]
}
}
}Instalar GitHub MCP en VS Code CLI
$ code --add-mcp '{"name":"github-mcp","type":"stdio","command":"uvx","args":["jaimenbell-github-mcp"]}'Instalar GitHub MCP en Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"github-mcp": {
"command": "uvx",
"args": [
"jaimenbell-github-mcp"
]
}
}
}Instalar GitHub MCP en Codex
$ codex mcp add github-mcp -- uvx jaimenbell-github-mcpInstalar GitHub MCP en Codex config.toml
~/.codex/config.toml
[mcp_servers.github-mcp] command = "uvx" args = ["jaimenbell-github-mcp"]
Instalar GitHub MCP en Gemini CLI
$ gemini mcp add -s user github-mcp uvx -- jaimenbell-github-mcpInstalar GitHub MCP en Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"github-mcp": {
"command": "uvx",
"args": [
"jaimenbell-github-mcp"
]
}
}
}Herramientas de GitHub MCP 14
Detectado desde el READMEget_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 | — |
Mostrar las 14 herramientasMostrar menos herramientas
add_labelscreate_pr_review_comment
| add_labels | — | |
| create_pr_review_comment | — |
Configuración
GITHUB_MCP_ENABLE_WRITEGITHUB_MCP_LIVEGITHUB_TOKEN
| Nombre | Descripción | Tipo |
|---|---|---|
| GITHUB_MCP_ENABLE_WRITE | — | |
| GITHUB_MCP_LIVE | — | |
| GITHUB_TOKEN | — |
Verificaciones automáticas
Ejecutado 14 nov 2026Informe completo →Pasó nuestras verificaciones automáticas. Esto no es una auditoría de seguridad: lee el código y dale al servidor el acceso más limitado que necesite. Cómo funcionan las verificaciones
- Repositorio de origen vinculado y accesiblejaimenbell/github-mcp is public and reachablegithub.com/jaimenbell/github-mcp ↗Aprobado
- El paquete indica este repositorio como su origenNo verificado
- Procedencia de la compilación (atestación de Sigstore)No build attestation published for this releaseNo verificado
- Licencia de código abierto (OSI)MITspdx.org/licenses/MIT.html ↗Aprobado
- Commit o lanzamiento en el último añoLast commit or release 2026-08-12github.com/jaimenbell/github-mcp ↗Aprobado
- OpenSSF ScorecardNo verificado
- El nombre del paquete no es similar a un paquete popularNo popular package one edit away from jaimenbell-github-mcpAprobado
- No hay avisos críticos en el paquete ni en sus dependencias69 resolved dependencies checked; no critical advisoryosv.dev ↗Aprobado
- Sin instrucciones ocultas para el modelo14 tool descriptions and the README read; no override phrases, credential paths or hidden charactersAprobado
- Las herramientas destructivas están etiquetadasNo tool named like delete, drop or execAprobado
- El endpoint remoto responde al handshake de MCPNo verificado
README
Ver en GitHubgithub-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
Preguntas sobre GitHub MCP
¿Cómo agrego GitHub MCP a Claude Code?
Ejecuta claude mcp add github-mcp -- uvx jaimenbell-github-mcp en tu terminal. Añade --scope user para que esté disponible en todos los proyectos.
¿Cómo agrego GitHub MCP a Cursor?
Abre ~/.cursor/mcp.json y añade el servidor en mcpServers, usando la configuración de Cursor que se muestra en la sección de instalación de arriba.
¿Qué herramientas proporciona GitHub MCP?
Expone 14 herramientas, incluidas get_repo, list_issues, get_issue, list_pull_requests, get_pull_request.
¿Este servidor permite escribir en GitHub de forma predeterminada?
No, las operaciones de escritura están desactivadas por defecto por seguridad. Debes habilitarlas explícitamente configurando la variable de entorno GITHUB_MCP_ENABLE_WRITE en 1.
¿Necesito un token de GitHub para leer datos de un repositorio?
No, las herramientas de lectura funcionan sin autenticación utilizando el nivel no autenticado de GitHub, aunque estarás sujeto a un límite de tasa más bajo de 60 solicitudes por hora.
¿Qué ocurre si intento usar una herramienta de escritura sin haberla habilitado o sin proporcionar un token?
El servidor devuelve errores estructurados: un error policy_refusal si el grupo de escritura está desactivado, o un error auth_required si el grupo está habilitado pero no se proporciona un token.