slim-github-mcp

Ein GitHub-MCP-Server mit Nur-Lese-Zugriffn, der kompakte Ergebnisse zurückgibt.

Die meisten GitHub-MCP-Server übergeben dem Modell rohe GitHub-API-Objekte. Das ist für ein Frontier-Modell hinter einer schnellen API in Ordnung, für ein lokales Modell aber mühsam: Eine einzelne Seite mit Repository-Suchergebnissen ist rund 14 KB JSON (~3.5k Tokens), meist URLs und Berechtigungsflags, die niemand liest. Dazu kommen ~7k Tokens an Tool-Schemas, und ein lokal gehostetes Modell kann Minuten für „meine Repositories auflisten“ verwenden – oder nie fertig werden.

Dieser Server verfolgt den gegenteiligen Ansatz. Jedes Tool liefert eine Handvoll nützlicher Felder, jede Liste ist serverseitig begrenzt, und die gesamte Tool-Oberfläche besteht aus neun Funktionen. Das Modell kann keine riesige Data erfolgt nicht, egal welche Argumente es erfindet.

Tools

Jeder limit ist standardmäßig 10 und wird auf 30 begrenzt. gh_file kappt bei 20.000 Zeilen und vermittelt das über ein truncated-Flag. Repos kommen zurück as full_name, private, eine 160-Zeichen große description, language, stars, updated, url – nichts anderes.

Es gibt absichtlich keine Pfad für Schreibzugriffe: Der Client führt ausschließlich GET an api.github.com aus.

Related MCP server: GitHub MCP Server

GitHub-Token erhalten

Der Server benötigt ein einziges Token, das für jeden Aufruf verwendet wird. Es sind nur Leserechte erforderlich.

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

2. Setze eine Gültigkeitsdauer und wähle, welche Repos das Token sehen darf – Public sources only, wenn private Daten nicht GitHub frisch sollen, oder All repositories, falls gh_my_repos(visibility="private") funktionieren soll.

3. Unter Repository permissions gewähre Leserechte für das, was du wirklich brauchst:

   • Metadata: Read-only – erforderlich, ist für Repo-Auflistungen und Such

   • Contents: Read-only – für gh_file und gh_commits

   • Issues: Read-only – für gh_issues

   • Pull requests: Read-only – für gh_pulls

4. Lasse alle Account permissions unberührt.

5. Kopiere das Token – GitHub zeigt es nur einmal.

Ein klassisches Token mit dem repo Scope funktioniert ebenfalls, ist aber deutlich umfassender als nötig. Bevorzugt wird grobaktionierte Token.

Nicht authentifizierte GitHub-API-Aufrufe sind auf 60 Anfragen pro Stunde abgesetzt, daher ist ein Token in der Praxis nicht optional. Mit einem Token sind es 5.000 pro Stunde.

Installation

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

Starte es:

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

Prüfe, ob es fehlerfrei hochgefahren und ob die Token funktioniert:

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'

Der MCP-Endpunkt selbst ist:

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

Der Server spricht streamable HTTP, jeder MCP-Client, der eine URL akzeptiert, kann es verwenden.

Konfiguration

Setz GITHUB_MCP_SECRET, falls der Port von etwas anderem als localhost erreichbar ist. Der Server hält ein Token, das möglicherweise private Repos lesen kann, und es gibt sonst keine Authentificate-Anrufer. Erzeuge eines mit openssl rand -hex 24.

GITHUB_MCP_PUBLIC_HOST existiert, weil MCP standardmäßig DNS-Rebinding-Schutz aktiviert: Anfragen über Reverse Proxy enthalten den öffentlichen Host-Header und werden abgewiesen, wenn dieser Hostname nicht unterrichtig ist. Symptom: 400 vom MCP-Endpunkt, während /api/health korrekt antwortet.

Als Dienst ausführen

scripts/github-mcp.service ist eine systemd-Unit zum Anpassen – setze User, die Pfade und verweise mit EnvironmentFile auf eine root-gehörte 0600-Datei mit oben den Variablen. Bewahre das Token außerhalb der Unit-Datei.

Außerdem gibt es ein 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

Hinter einem Reverse-Proxy

Nichts ungewöhnlich, aber MCP streamt, daher muss / buffing abgestellt sein:

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;
}

Setze GITHUB_MCP_PUBLIC_HOST auf den Hostname, von dem du den Reverse-PROXY verwendest.

Verwenden mit Open WebUI

Open WebUI spricht MCP nativ (0.6.x und neuer). Registriere den Server mit dem Hilfsskript:

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

Das Skript führt den Eintrag in vorhandene Tool-Server von Open WebUI zusammen (abgeglichen per ID, ein erneutes Ausführen nur aktualisiert) und gibt anschließend die erkannten Tools aus:

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

Um es manuell zu machen: Admin Settings → Tools → Add Tool Server, wähle Typ MCP, URL wie oben, Auth Bearer mit deinem Secret.Dinge, die man leicht übersieht:

• Aktiviere das Tool in der Chat-Tool-Auswahl. Ein registrierter Server wird dem Modell nicht automatisch angeboten.

• Wenn du per Modell Tools anpinnt nichts (Workspace → Models → Tools), füge es auch dort hinzu. Open WebUI speichert das als server:mcp:<id>. Benennst du die Server-Id später um, löst sich der Pin lautlos in nichts auf – das Modell antwortet weiter, nur ohne die Tools, meist einfach. Raten.

Wissenswert: Direktes Aufrufen von /api/chat/completions mit tool_ids bindet Tool-Server nicht an. Die Tool-Verkabelung geschieht im Frontend, daher teste über die UI.

Lizenz

MIT