GitHub MCP Server

Ein Projekt, das einem KI-Assistenten mithilfe sicherer, strukturierter Tools ermöglicht, mit GitHub zu sprechen.

In einfachen Worten: Anstatt dass die KI rät, wie GitHub funktioniert, erhält sie von diesem Projekt ein klares Aktionsmenü – etwa „meine Repos auflisten“, „offene Issues anzeigen“ oder „Datei lesen“. Die KI wählt die richtige Aktion, dieser Server spricht mit GitHub, und die Antwort kommt in einem sauberen Format zurück, das die KI verstehen kann.

Welches Problem wird gelöst?

Chatbots sind sprachlich stark, aber sie haben nicht automatisch Live-Zugriff auf dein GitHub-Konto.

Dieses Projekt baut eine Brücke:

1. Du fragst etwas in normaler Sprache („Zeige offene Issues in microsoft/vscode“).

2. Ein KI-Modell (über Groq) entscheidet, welches GitHub-Tool verwendet wird.

3. Der MCP-Server führt dieses Tool gegen die echte GitHub-API aus.

4. Die Ergebnisse werden bereinigt (normalisiert) und an die KI zurückgegeben.

5. Die KI erklärt dir das Ergebnis in einfacher Sprache.

MCP steht für Model Context Protocol. Stell es dir wie einen Standardstecker vor: Jeder kompatible KI-Client kann sich mit diesem Server verbinden und seine Tools nutzen.

Related MCP server: GitHub MCP Server

Gesamtbild (Architektur)

You
  ↓
AI Agent (client/agent.py)  ← talks to Groq LLM
  ↓
MCP Server (notebooks/server.py)  ← menu of GitHub tools
  ↓
GitHub Client  ← HTTP calls with your token
  ↓
GitHub REST API
  ↓
GitHub

Designregel (wichtig)

Tools bleiben schlank:

1. Prüfe die Eingabe (ist der Repository-Name gültig?).

2. Rufe den GitHub-Client auf.

3. Normalisiere die Antwort in eine stabile Form.

4. Gib die sauberen Daten an den Agenten zurück.

Alle lästigen GitHub-Details bleiben in der Client-Schicht – nicht verstreut Über die Tools.

Projektordner (wozu jeder Teil dient)

Was du mit den Tools und Aktionen machen kannst

Der Server gibt eine Vielzahl von GitHub-Aktionen. Einfach gruppiert:

Lesen (sicher erkunden)

• Deine Repositories auflisten

• Repository-Details abrufen

• Issues und Pull Requests auflisten/abrufen

• PR-Diffs auflisten

• Branches, Commits, Labels auflisten

• Suche in einem Repo

• Dateiinhalte lesen

• GitHub-Actions-Workflow-Läufe auflisten

Schreiben (verändert GitHub)

• Issues, Kommentare, PRs, Branches, Labels erstellen

• Issues aktualisieren, Labels hinzufügen/entfernen

• Issues wieder öffnen

Destructive (kann Schaden verursachen – geschützt)

Diese benötigen standardmäßig eine Bestätigung:

• merge_pull_request

• delete_file

• create_repository

• create_or_update_file

• close_issue

Dafür sollte der Agent normalerweise:

1. Mit dry_run=true aufrufen → nur Vorschau

2. Noch einmal mit confirm=true aufrufen → tatsächlich ausführen

Du kannst das über Umgebungsvariablen enger oder lockerer gestalten (siehe unten).

Normalisierte Antworten (warum Agenten das mögen)

Rohe GitHub-Antworten sind riesig und ändern sich oft. Dieses Projekt liefert stabile Strukturen.

Listen-Tools sehen immer gleich so aus:

{
  "count": 20,
  "items": [ ... ],
  "page": 1,
  "per_page": 20,
  "has_next": true,
  "has_prev": false,
  "next_page": 2,
  "prev_page": null,
  "last_page": 5
}

Um die nächste Seite zu bekommen, rufst du dasselbe Tool erneut mit page=2 auf (oder page=next_page).

Issue-Beispiel:

{
  "number": 42,
  "title": "Bug in login",
  "state": "open",
  "author": "some-user",
  "labels": ["bug"],
  "comments": 3,
  "html_url": "https://github.com/...",
  "is_pull_request": false
}

Zudem: get_issues filtert Pull Requests heraus (die GitHub-Issues-API mischt sie sonst mit ein).

Sicherheitsfunktionen

Umgebungsvariablen (optional):

GITHUB_MCP_DESTRUCTIVE_MODE=confirm
GITHUB_MCP_DESTRUCTIVE_ALLOWLIST=merge_pull_request,delete_file

Protokollierung (Debugging)

Server schreibt JSON-Logs nur auf stderr.

Warum stderr? MCP nutzt stdout für das Protokoll. Würdest du Protokolltexte dort einführen, bräche die KI-Verbindung.

Logs enthalten z. B.:

• Anfragemethode und -pfad

• HTTP-Status

• Dauer

• Rate-Limit-Restfee

niemals geloggt:

• dein GitHub-Token

• Authorization-Header

• sicherheitsrelevante Werte (PATs, Bearer-Tokens usw.)

Beispiel einer Log-Zeile:

{"ts":"2026-08-23T12:00:00+00:00","level":"INFO","event":"github_request","method":"GET","path":"/repos/microsoft/vscode/issues","status_code":200,"duration_ms":120.5}

Der KI-Agent (client/agent.py)

Der Agent:

1. Startet den MCP-Server als Unterprozess (notebooks/server.py).

2. Der Fragt den Server nach der Werkzeugliste.

3. Er fragt deine Frage + Tools an Groq.

4. Wenn Groq ein Tool verwenden will, ruft der Agent es via MCP auf.

5. Das Tool-Ergebnis wird an Groq zurückgegeben, um eine endgültige Antwort zu erstellen.

Nützliche Befehle (aus dem Projektordner, mit aktiver virtueller Umgebung):

# See all registered tools
python client/agent.py --list-tools

# Only show which tool the AI would pick (no GitHub write)
python client/agent.py --dry-run "list my github repos"

# One real question, then exit
python client/agent.py --once "show open issues for microsoft/vscode"

# Interactive chat
python client/agent.py

# Check tool-picking quality on many sample prompts
python client/test_tool_picking.py

Schleifenbegrenzungen (optional):

python client/agent.py --max-rounds 5 --once "..."

Oder in .env:

AGENT_MAX_TOOL_ROUNDS=8
AGENT_MAX_TOOL_CALLS=16
AGENT_MAX_CONSECUTIVE_ERRORS=3

Umgebungsvariablen

Erforderlich für den MCP-Server

Erforderlich für den Agenten (Chat / Tool-Auswahl)

Optional

Kopiere .env.example → .env und setze echte Werte ein. Details siehe SETUP.md.

Tech-Stack

• Python 3.13+ (Projekt auf 3.13 entwickelt)

• MCP (mcp Python-Paket) – Tool-Server-Protokoll

• httpx – HTTP-Client für GitHub

• Pydantic – Schemas / Validierung

• python-dotenv – lädt Datei .env

• OpenAI-kompatibler Client – für Groq-LLM

• Jupyter (optional) – Hauptnotebook

Einrichtung & Ausführung

Folge der Anleitung:

👉 SETUP.md – Python installieren, Schlüssel, Git-Commit, .env einrichten und erste Befehle ausführen.

Kurzfassung (falls du Python bereits kennst):

cd "path\to\Github-MCP-server"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
# edit .env with your tokens
python client/agent.py --list-tools
python client/agent.py --once "list my github repos"

Lernpfad (empfohlen)

1. README dieses README (du bist).

2. SETUP.md bis --list-tools funktioniert.

3. docs/ARCHITECTURE_HLD_LLD.md lesen für HLD + LLD-Abläufe.

4. --dry-run und --once mit einfachen Read-Only-Tests versuchen.

5. Manuellen Testplan mit 50 Szenarien ausführen: tests/MANUAL_TESTING_50_SCENARIOS.md

   • python client/run_manual_scenarios.py für (Auto-Auswahl)

6. notebooks/01_github_mcp_server.ipynb öffnen und schauen, wie jede Schicht gebaut ist.

7. Erst dann Schreib-/destructive Tools mit dry_run + confirm testen.

Fehlerbehebung (kurz)

Sicherheitshinweise

• .env niemals kommittieren.

• Nie deine GitHub-/Groq-Tokens im Chat, Screenshots oder in GitHub-Issues posten.

• Bevorzuge ein GitHub-Token mit nur den benötigten Definitionen.

• GITHUB_MCP_DESTRUCTIVE_MODE auf confirm oder deny lassen – außer du vertraust der Umgebung vollständig.

• Ausgabe von server_1.py nicht teilen; nur server.py verwenden.

Lizenz / Inhaberschaft

Dieses ist ein persönliches / Lern-Gen-AI-Projekt für einen GitHub-MCP-Server und -Agenten. Vor einer öffentlichen Veröffentlichung Besitzer und Lizenz passend ändern.