GithubMCP

Un servidor MCP de asistente de desarrollo personal de nivel de producción

Conecta sin esfuerzo los modelos de IA (Claude, Cursor, etc.) con tus flujos de trabajo de GitHub, pipelines de CI/CD, contexto del espacio de trabajo local y herramientas de análisis de código.

Descripción general

GithubMCP es un servidor de Model Context Protocol (MCP) diseñado para desarrolladores. Conecta los asistentes de IA directamente con tu entorno de desarrollo, lo que les permite:

• Inspeccionar repositorios de GitHub, pull requests, issues, commits y código en repositorios públicos y privados.

• Gestionar la privacidad y visibilidad de los repositorios (público/privado) directamente mediante la conversación.

• Supervisar las ejecuciones de flujos de trabajo de CI/CD y analizar los pasos de compilación fallidos de GitHub Actions.

• Inspeccionar de forma segura los espacios de trabajo locales del sistema de archivos dentro de las rutas permitidas definidas por el usuario.

• Analizar la calidad del código, calcular métricas de complejidad, encontrar TODOs y detectar posibles riesgos de seguridad (secretos hardcodeados).

Admite los modos de transporte STDIO (Claude Desktop, Cursor) y SSE (Server-Sent Events para clientes web).

Related MCP server: GitHub MCP Server

Referencia del conjunto de herramientas

GithubMCP proporciona 13 herramientas especializadas:

Inicio rápido

1. Requisitos previos

• Python 3.11+

• uv (Gestor de paquetes de Python rápido)

Instala uv (si no lo tienes ya instalado):

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clonación y configuración

git clone https://github.com/Dhananjayrbiraris/github-mcp.git
cd github-mcp

# Install dependencies and sync virtual environment
uv sync

3. Configuración del entorno

Copia la plantilla .env.example a .env:

cp .env.example .env

Edita el archivo .env con tu token de acceso personal de GitHub:

# GitHub Personal Access Token (Classic PAT with 'repo', 'workflow', 'read:user' scopes)
GITHUB_TOKEN=ghp_your_github_token_here

# Default GitHub Username (Optional)
GITHUB_USERNAME=your_username

# Sandboxed directories allowed for local filesystem operations
ALLOWED_PATHS=["~/projects", "~/workspace", "."]

# Max file size limit in MB for reading files
MAX_FILE_SIZE_MB=10

# Default Transport mode: "stdio" or "sse"
TRANSPORT=stdio

Genera tu token de GitHub: Ve a GitHub Settings -> Developer Settings -> Personal access tokens (classic) y genera un token con los ámbitos repo, workflow y read:user.

Guías de configuración del cliente

A. Claude Desktop

1. Abre el archivo de configuración de Claude Desktop:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

2. Añade el servidor github-mcp:

{
  "mcpServers": {
    "github-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/github-mcp",
        "run",
        "python",
        "-m",
        "github_mcp.main",
        "--transport",
        "stdio"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token_here"
      }
    }
  }
}

(En Windows, usa barras invertidas, p. ej., C:\\Users\\yourname\\path\\to\\github-mcp, o barras normales).

3. Reinicia Claude Desktop

Abre Claude Desktop y haz clic en el icono de Tools en la parte inferior derecha del cuadro de solicitud para ver todas las herramientas de GithubMCP conectadas.

4. Cursor IDE

En Cursor:

1. Ve a Cursor Settings -> Features -> MCP.

2. Haz clic en + Add New MCP Server.

3. Rellena los campos:

   • Name: github-mcp

   • Type: command

   • Command: uv --directory /path/to/github-mcp run python -m github_mcp.main --transport stdio

5. Server-Sent Events (SSE) Mode / Web Clients

Para ejecutar el servidor MCP sobre HTTP / Server-Sent Events:

uv run python -m github_mcp.main --transport sse --host 0.0.0.0 --port 8000

El endpoint SSE estará disponible en: http://localhost:8000/sse

Seguridad y sandboxing

1. Sandbox de rutas: Las herramientas de sistema de archivos local (read_file, list_directory, search_local_files, get_project_context) aplican estrictamente una validación de recorrido de rutas contra ALLOWED_PATHS. Acceder a rutas fuera de la lista de rutas permitidas generará un SecurityError.

2. Gestión de secretos: Los tokens y las credenciales nunca se registran ni se exponen.

3. Resiliencia ante límites: Se aplican reintentos automáticos con una estrategia de espera exponencial ante la limitación de velocidad de la API de GitHub.

Desarrollo y pruebas comandos

Ejecuta la suite completa de pruebas y calidad (testing and quality check suite):

# Run pytest unit tests
uv run pytest

# Run linter
uv run ruff check .

# Check code formatting
uv run ruff format --check .

# Run strict type checking
uv run mypy src/

Estructura del repositorio

github-mcp/
├── .github/workflows/ci.yml # GitHub Actions CI workflow
├── src/github_mcp/
│   ├── __init__.py
│   ├── main.py              # Server entrypoint & MCP tool registrations
│   ├── config.py            # Pydantic Settings model
│   ├── github_tools.py      # GitHub API integrations & visibility controls
│   ├── file_tools.py        # Sandboxed local filesystem operations
│   ├── ci_tools.py          # GitHub Actions CI/CD monitoring
│   ├── analysis_tools.py    # Diff categorization & code quality analyzer
│   └── utils.py             # Path safety, error handling, rate limiting
├── tests/
│   ├── conftest.py          # Pytest fixtures and mocks
│   ├── test_github.py       # GitHub tools unit tests
│   ├── test_files.py        # Filesystem tools unit tests
│   └── test_ci.py           # CI status tools unit tests
├── docs/
│   ├── architecture.md      # System architecture & data flow
│   └── tools_reference.md   # Complete API schemas for all 13 tools
├── pyproject.toml           # Project dependencies & tool configurations
├── .env.example             # Environment variable template
├── CONTRIBUTING.md          # Open-source contribution guidelines
├── SECURITY.md              # Security policy & vulnerability reporting
└── LICENSE                  # MIT License

Licencia

Este proyecto está bajo la Licencia MIT — libre para uso personal y comercial.