slim-github-mcp

Un servidor MCP de GitHub de solo lectura que devuelve resultados pequeños.

La mayoría de los servidores MCP de GitHub le pasan al modelo los objetos sin procesar de la API de GitHub. Eso está bien para un modelo de frontera detrás de una API rápida, pero es un problema para uno local: una sola página de resultados de búsqueda de repositorios pesa alrededor de 14 KB de JSON (~3,5k tokens), la mayor parte URL y banderas de permisos que nadie va a leer. Añade ~7k tokens de esquemas de herramientas y un modelo alojado localmente puede pasarse minutos en «lista mis repositorios» — o no terminar nunca.

Este servidor adopta la posición contraria. Cada herramienta devuelve un puñado de campos útiles, cada lista tiene un límite por parte del servidor y toda la superficie de herramientas son nueve funciones. El modelo no puede obtener un payload enorme, sin importar qué argumentos invente.

Herramientas

Todos los limit usan 10 por defecto y se limitan a un máximo de 30. gh_file trunca a 20k caracteres y lo indica mediante una bandera truncated. Los repos se devuelven como full_name, private, una description de 160 caracteres, language, stars, updated, url — nada más.

No hay, a propósito, ruta de escritura: el cliente solo hace GET a api.github.com.

Related MCP server: GitHub MCP Server

Obtención de un token de GitHub

El servidor necesita un token, que se usa en todas las llamadas. Solo se requerirá acceso de lectura.

1. Ve a GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token.

2. Establece una fecha de caducidad y elige qué repositorios puede ver el token: Public repositories only si no quieres que los datos privados salgan tarde de GitHub, o All repositories si quieres que gh_my_repos(visibility="private") funcione.

3. En Repository permissions, otorga solo lectura a lo que realmente necesitas:

   • Metadata: Read-only — obligatorio, y suficiente para la enumeración de repos y la búsqueda

   • Contents: Read-only — para gh_file y gh_commits

   • Issues: Read-only — para gh_issues

   • Pull requests: Read-only — para gh_pulls

4. Deja todos los Account permissions sin tocar.

5. Copia el token: GitHub solo lo muestra una vez.

Un token clásico con alcance repo también funciona, pero es mucho más amplio de lo que este servidor necesita; preferible usar uno fine-grained.

Las llamadas no autenticadas a la API de GitHub están limitadas a 60 peticiones/hora, así que un token no es opcional en la práctica. Con uno obtienes 5.000/hora.

Instalación

git clone https://github.com/0xBakeer/slim-github-mcp.git
cd slim-github-mcp

python3 -m venv venv
./venv/bin/pip install -r requirements.txt

cp .env.example .env
$EDITOR .env            # put your token in GITHUB_MCP_TOKEN

Ejecútalo:

set -a; . ./.env; set +a
./venv/bin/uvicorn slim_github_mcp.main:app --host 127.0.0.1 --port "${GITHUB_MCP_PORT:-9130}"

Comprueba que ha arrancado y que el token funciona:

curl -s http://127.0.0.1:9130/api/health
curl -s -H "Authorization: Bearer $GITHUB_MCP_SECRET" \
     'http://127.0.0.1:9130/api/my-repos?visibility=public&limit=5'

El endpoint MCP en sí mismo es:

http://127.0.0.1:9130/tools/mcp/v1

Habla HTTP de transmisión (streamable HTTP), por lo que cualquier cliente MCP que acepte una URL puede usarlo.

Configuración

Establece GITHUB_MCP_SECRET si el puerto es accesible por todo lo que no sea localhost. El servidor alberga un token que puede leer tus repositorios privados y, de lo contrario, no autentica a los llamantes. Genérate uno con openssl rand -hex 24.

GITHUB_MCP_PUBLIC_HOST existe porque MCP habilita la protección contra rebinding de DNS por defecto: las peticiones que llegan a través de un proxy inverso llevan el Host público y se rechazan a menos que ese hostname esté declarado. El síntoma de olvidarlo es un 400 en el endpoint MCP mientras /api/health responde bien.

Ejecución como servicio

scripts/github-mcp.service es una unidad de systemd para adaptarse: define User, las rutas y apunta EnvironmentFile a un archivo 0600 propiedad el root que contenga las variables de arriba. No pongas el token dentro del archivo de la unidad.

También hay un Dockerfile:

docker build -t slim-github-mcp .
docker run -d --name github-mcp -p 127.0.0.1:9130:9130 --env-file .env slim-github-mcp

Detrás de un proxy inverso

No hay nada inusual, pero MCP es un streaming por lo que tampoco:

location /tools/mcp/ {
    proxy_pass http://127.0.0.1:9130;
    proxy_set_header Host $host;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 3600s;
}

Establece GITHUB_MCP_PUBLIC_HOST al hostname del que se ejecuta tu proxy.

Uso de Open WebUI con Open WebUI

Open WebUI habla MCP de forma nativa (0.6.x y posteriores). Registra el servidor con el script auxiliar:

export OPEN_WEBUI_URL=https://webui.example.com
export OPEN_WEBUI_KEY=sk-...                      # Settings -> Account -> API keys
export GITHUB_MCP_URL=http://127.0.0.1:9130/tools/mcp/v1
export GITHUB_MCP_SECRET=...                      # if you set one

./scripts/register-open-webui.sh

Combina la entrada con los servidores de herramientas existentes de Open WebUI (coincide por el id, de modo quevolver a ejecutarla simplemente la actualiza) y luego imprime las herramientas que ha descubierto:

==> Verifying tool discovery
    9 tools: gh_whoami, gh_my_repos, gh_user_repos, ...

Para hacerlo a mano: Admin Settings → Tools → Añadir servidor de servidor, selecciona MCP, la URL como que arriba, autenticación Bearer con tu secreto.

Dos cosas que se escapan fácilamente:

• Habilita la herramienta en el selector de herramientas del chat. Un servidor registrado no se ofrece automáticamente al modelo.

• Si tienes herramientas fijadas por modelo (Workspace → Models → Tools), añádelas ahí también. Open WebUI lo guarda como server:mcp:<id>. Si luego reproduces el id del servidor, la referencia fijada se resuelve en a nada en silencio: el modelo sigue respondiendo, solo que sin la herramientas, normalmente adivinando.

Vale la pena saberlo: llamar directamente a /api/chat/completions con tool_ids no acopla los servidores de herramientas. La conexión de las herramientas se produce en el frontend, así que pruebalo a través de la interfaz.

Licencia

MIT