grc-evidence-mcp – Schritt-für-Schritt-Bauanleitung

Baue ein echtes, schreibgeschütztes GRC-Evidence-Collection-MCP in Python, verbinde es mit Claude Desktop, teste es gegen dein eigenes GitHub-Repository und füge optional visuelle Evidence-Erfassung mit Playwright hinzu.

Dieser Leitfaden ist so geschrieben, dass du den Bau abschließen kannst, auch wenn du noch nie ein MCP gebaut hast. Wenn du bereits mit Python, Terminals, APIs oder Claude Code vertraut bist, kannst du schneller vorgehen und die Erklärungen nur bei Bedarf nutzen.

Fertiges Repository: [GITHUB REPO LINK]

Was du baust

Am Ende kann dein MCP:

1. Die Evidence-Quellen auflisten, die es kennt.

2. Echte GitHub-Evidence für Branch Protection und CODEOWNERS sammeln.

3. Diese Evidence Kontrollreferenzen zuordnen.

4. Die vollständige Evidence lokal in SQLite speichern und Claude nur eine undurchsichtige collection_id zurückgeben.

5. Eine gespeicherte Evidence-Collection anhand ihrer ID abrufen.

6. Optional einen echten Webseiten-Screenshot mit Playwright aufnehmen und als visuelle Evidence speichern.

Die Designregel für das gesamte Projekt ist einfach: Lies Evidence VOM geprüften System; schreibe Evidence nur IN deine lokale Landing Zone. Ändere niemals das geprüfte System.

Wähle dein Tempo

Du kannst den Bau in einer Sitzung abschließen, indem du dem Leitfaden von oben nach unten folgst, oder ihn auf fünf Tage verteilen.

Related MCP server: Change Trace MCP

5-Tage-Pfad

Tag 1 – Claude Code einrichten und das Fundament bauen

Ziel: Ein funktionierendes MCP-Projekt mit lokaler Evidence-Speicherung und einem sichtbaren Tool.

Aktionen:

• Claude Code installieren.

• Einen leeren Projektordner erstellen.

• Claude Code im Ordner starten.

• Prompt 1 einfügen.

• Claude Code das Python-Projekt, den SQLite-gestützten StateStore und das Tool list_evidence_sources erstellen lassen.

• Das Projekt lokal ausführen und Installationsfehler beheben, bevor du weitermachst.

Erledigt, wenn: Claude Code das MCP ausführen kann und list_evidence_sources existiert.

Tag 2 – Das MCP mit Claude Desktop verbinden

Ziel: Claude Desktop das von dir gebaute MCP sehen lassen.

Aktionen:

• Prompt 2 in Claude Code einfügen.

• Claude Code die Claude-Desktop-MCP-Konfiguration mit dem vollständigen Serverpfad aktualisieren lassen.

• Claude Desktop vollständig beenden und neu öffnen.

• Einen neuen Chat öffnen und das Tools/Hammer-Symbol prüfen.

Erledigt, wenn: list_evidence_sources als Tool in Claude Desktop erscheint.

Tag 3 – Die echte GitHub-Evidence-Quelle hinzufügen

Ziel: „Nur-Demo“-Denken durch einen echten schreibgeschützten API-Aufruf ersetzen.

Aktionen:

• Prompt 3 einfügen.

• Ein feingranulares GitHub-Personal-Access-Token mit nur den für diesen Bau erforderlichen Berechtigungen erstellen.

• .env.example zu .env kopieren und das Token dort hinzufügen.

• Das Token selbst niemals in Claude Desktop oder Claude Code Chat einfügen.

• Claude Desktop nach den Umgebungs-/Konfigurationsänderungen neu starten.

Erledigt, wenn: Das MCP ein funktionierendes collect_evidence-Tool hat und dein Token dem Server zur Verfügung steht.

Tag 4 – Echte Evidence testen, abrufen und prüfen

Ziel: Beweisen, dass dein MCP gegen ein Repository funktioniert, das du tatsächlich kontrollierst.

Aktionen:

• Den GitHub-Testprompt gegen dein eigenes Repository ausführen.

• Die zurückgegebene collection_id kopieren.

• Claude Desktop bitten, diese Collection abzurufen.

• Die Branch-Protection- und CODEOWNERS-Ergebnisse prüfen.

• Den Abschnitt zur 404-Einschränkung lesen, bevor du ein „nicht vorhandenes“ Ergebnis als Kontrolllücke behandelst.

Erledigt, wenn: Du einen gespeicherten Datensatz abgerufen hast, der durch einen echten GitHub-API-Aufruf erzeugt wurde.

Tag 5 – Visuelle Evidence hinzufügen, aufräumen und veröffentlichen

Ziel: Das Projekt in etwas Veröffentlichungsreifes verwandeln.

Aktionen:

• Die optionale Playwright-Erweiterung und Chromium installieren.

• collect_visual_evidence hinzufügen oder überprüfen.

• Einen Screenshot einer echten Seite aufnehmen, auf die du zugreifen darfst.

• Die Screenshot-Evidence-Collection abrufen und ihre Metadaten prüfen.

• Deine README aufräumen, bestätigen, dass .env ignoriert wird, und das Projekt auf GitHub pushen.

• Wenn du an der Challenge teilnimmst, reiche dein Repository gemäß den Challenge-Anweisungen ein.

Erledigt, wenn: Dein Repository erklärt, was das MCP tut, wie man es ausführt, welche Einschränkungen es hat, und keine Geheimnisse enthält.

Bevor du beginnst

Du benötigst:

• Einen Computer mit Terminal.

• Ein Claude-Konto, das Claude Code verwenden kann.

• Claude Desktop für den Desktop-Tool-Teil der Anleitung.

• GitHub-Kontozugriff und mindestens ein Repository, das du testen darfst.

• Python 3.10 oder neuer.

• Node.js, falls dein Rechner es nicht bereits hat.

Wenn du völlig neu bist

Du musst nicht jede Zeile Python verstehen, bevor du beginnst. Deine Aufgabe während dieses Baus ist es, zu verstehen, wofür jede Komponente verantwortlich ist, welche Daten hineingehen, was zurückkommt und wo die Sicherheitsgrenzen liegen. Wenn Claude Code eine Datei erstellt oder ändert, bitte es, dir die Datei in einfachem Englisch zu erklären, bevor du weitermachst, falls du unsicher bist.

Wenn du technisch versierter bist

Du kannst die generierten Dateien inspizieren, zwischen den Prompts Tests ausführen und Claude Code bei Implementierungsentscheidungen herausfordern. Das fertige Repository ist eine Referenzimplementierung, keine Anforderung, dass jede Datei identisch aussieht.

Schritt 1 – Claude Code installieren

Führe aus:

npm install -g @anthropic-ai/claude-code

Wenn das wegen fehlendem Node.js einen Fehler ergibt, installiere Node.js und führe den Befehl dann erneut aus.

Starte Claude Code:

claude

Beim ersten Start wirst du aufgefordert, dich anzumelden.

Dieser Bau ist bewusst terminal-zuerst. Du benötigst keinen separaten Editor, um ihn abzuschließen.

Schritt 2 – Deinen Projektordner erstellen

mkdir my-evidence-mcp
cd my-evidence-mcp
claude

Füge ab jetzt die Bau-Prompts in der Reihenfolge in Claude Code ein.

Prompt 1 – Das Fundament bauen

Help me build a small MCP server in Python called grc-evidence-mcp, using
FastMCP over stdio, that I'll connect to Claude Desktop.

Purpose: read-only compliance evidence collection. It reads evidence FROM
systems and writes evidence TO a local landing zone — it must never modify
the audited system itself.

Build the foundation first, not real sources yet:

1. A StateStore class backed by SQLite — save(record) returns an opaque id,
   get(id) returns the record back. That id is the only handle anything
   else gets to a stored record.
2. One tool: list_evidence_sources — returns available sources and flags
   which ones are just stubs for now. Register one stub source so the
   list isn't empty.

Get this running and visible as a tool in Claude Code before we add
anything real.

Was dieser Schritt dir beibringt

Der StateStore trennt das Gespräch vom vollständigen Evidence-Datensatz. Anstatt alle gesammelten Evidence direkt an das Modell zurückzugeben, speichert der Server sie lokal und gibt Claude eine ID. Claude kann diese ID später weitergeben, ohne die Evidence selbst reproduzieren zu müssen.

Checkpoint

Bevor du weitermachst, bitte Claude Code, dir zu zeigen:

• wo der MCP-Server startet,

• wo StateStore Daten schreibt,

• wo list_evidence_sources registriert ist,

• und den Befehl, den es verwendet hat, um zu bestätigen, dass der Server erfolgreich startet.

Prompt 2 – Mit Claude Desktop verbinden

Add this server to my Claude Desktop config at ~/Library/Application
Support/Claude/claude_desktop_config.json. Use the full path to the
server, not just the command name, so it doesn't rely on my terminal's
PATH.

Dieser Pfad ist der macOS-Pfad, der in der Anleitung verwendet wird. Wenn du ein anderes Betriebssystem verwendest, bitte Claude Code, die Claude-Desktop-MCP-Konfigurationsdatei für dein Betriebssystem zu finden, bevor es etwas bearbeitet.

Verwende den vollständigen Pfad zum Serverbefehl. Claude Desktop erbt nicht unbedingt denselben PATH wie dein Terminal.

Beende dann Claude Desktop vollständig und öffne es erneut. Ein normales Schließen des Fensters oder ein Neuladen lädt die MCP-Konfiguration möglicherweise nicht neu.

Öffne einen neuen Chat und prüfe das Tools/Hammer-Symbol. Du solltest list_evidence_sources sehen.

Wenn du das Tool nicht siehst

Prüfe in dieser Reihenfolge:

1. Hat Claude Code die Konfiguration in der richtigen Claude-Desktop-Konfigurationsdatei gespeichert?

2. Verwendet die Konfiguration einen vollständigen ausführbaren/Serverpfad?

3. Startet das MCP erfolgreich von deinem Terminal?

4. Hast du Claude Desktop vollständig beendet und neu geöffnet?

5. Hast du nach dem Neustart einen neuen Chat geöffnet?

Fahre nicht mit dem GitHub-Schritt fort, bis das Fundament-Tool sichtbar ist.

Prompt 3 – Die echte GitHub-Quelle hinzufügen

Now build the first real source: GitHub.

Add a collect_evidence(source_name, params) tool that, for source_name=
"github", checks branch protection status and CODEOWNERS presence on a
repo I specify (owner/repo/branch), using my own GitHub token
(read-only — Administration:read and Contents:read, nothing else).

Map each result to a control reference:
- branch protection present → SOC2-CC8.1, ISO27001-A.8.32
- CODEOWNERS present → SOC2-CC8.1, ISO27001-A.5.3

Return a collection_id from StateStore, not the raw evidence directly.
I want to run this against a real repo of mine and see actual results,
not sample data.

Das GitHub-Token erstellen

Erstelle ein feingranulares Personal Access Token für das Repository, das du testen möchtest. Gewähre nur:

• Administration: Lesen

• Contents: Lesen

Verwende kein breiteres Token nur weil du bereits eines hast.

Das Token in .env ablegen

Das fertige Repository enthält .env.example. Kopiere es:

cp .env.example .env

Setze dann:

GITHUB_TOKEN=your_token_value_here

Das fertige Repository lädt diese .env-Datei, wenn der GitHub-Collector startet.

Füge das tatsächliche Token niemals in eine Claude-Desktop- oder Claude-Code-Nachricht ein. Das Token gehört in die Umgebung, nicht in das Gespräch. Halte .env auch in .gitignore, damit es nie committet wird.

Nachdem du Token/Umgebung geändert hast, starte Claude Desktop vollständig neu.

Schritt 4 – Gegen dein eigenes Repository testen

Frage in Claude Desktop:

Check branch protection and CODEOWNERS on [your-username]/[your-repo],
branch main.

Dies sollte einen echten GitHub-API-Aufruf gegen das von dir genannte Repository ausführen.

Das Tool sollte eine collection_id zurückgeben, nicht den vollständigen Rohdatensatz.

Frage dann:

Get the evidence collection with id [collection_id].

Du solltest jetzt den gespeicherten Evidence-Datensatz sehen.

Was zu prüfen ist

Achte auf:

• Repository- und Branchname,

• Branch-Protection-Ergebnis,

• CODEOWNERS-Ergebnis,

• zugeordnete Kontrollreferenzen,

• zugrunde liegende Evidence/Statusdetails,

• Zeitstempel der Collection.

An diesem Punkt wird das Projekt mehr als eine Demo: Du hast Evidence aus einem echten System gesammelt und abgerufen, das du kontrollierst.

Wichtige Einschränkung – GitHub-404s sind mehrdeutig

GitHub kann eine 404 zurückgeben, wenn Branch Protection nicht konfiguriert ist, aber eine 404 kann auch auftreten, weil das Repository/der Branch nicht gefunden werden kann oder der Aufrufer nicht genügend Zugriff hat, um die Einstellung zu bestätigen.

Der aktuelle GitHub-Collector bewahrt die Antwortdetails, zeichnet aber ein 404-Ergebnis dennoch als present: false auf. Behandle das nicht automatisch als bestätigte Kontrolllücke. Ein menschlicher Prüfer sollte verifizieren, ob das Ergebnis „nicht konfiguriert“ oder „konnte nicht bestätigt werden“ bedeutet.

Diese Unterscheidung ist Teil guter GRC-Technik: „Nein“ und „Ich weiß es nicht“ sind nicht dasselbe Ergebnis.

Bonus – Visuelle Evidence mit Playwright hinzufügen

Dies ist optional. Das Kern-MCP funktioniert auch ohne.

Das fertige Repository verwendet Playwright mit Headless-Chromium. Es hängt nicht von der Claude-for-Chrome-Erweiterung ab.

Installiere das optionale Paket und den Browser:

pip install -e ".[screenshot]"
playwright install chromium

Wenn du aus Prompts baust, verwende:

Add a tool collect_visual_evidence(url, subject) that opens the given URL
in headless Chromium via Playwright, captures a full-page screenshot, and
stores it the same way collect_evidence does — save the result to
StateStore, return only a collection_id, never the raw image bytes.

Classify the result conservatively: a successful page load can be stored
as present; a 401/403 authentication wall, a 404, or a navigation failure
must not be treated as proof that a control is missing. Record those as
indeterminate or error as appropriate. Burn a timestamp using the local
machine timezone into the screenshot metadata so a reviewer knows when
it was captured.

Versuche dann:

Capture visual evidence of https://github.com/[your-username]/[your-repo]/settings/branches.

Das Screenshot-Tool speichert das PNG im lokalen Screenshots-Verzeichnis des MCP und speichert seine Metadaten im StateStore. Es gibt eine neue collection_id für diesen Screenshot-Evidence-Datensatz zurück.

Ein Screenshot zeigt, wie die Seite zum Zeitpunkt der Aufnahme aussah. Er ist nicht alleiniger Beweis dafür, dass eine Kontrolle wirksam ist. Die Implementierung behandelt Authentifizierungswände und 404s bewusst als unbestimmt und nicht als Kontrollfehler. Die visuelle Erfassung ist seitenbezogen und macht keinen Screenshot deines lokalen Desktops.

Was das fertige Repository enthält

• grc_evidence_mcp/store.py – SQLite-gestützter StateStore mit undurchsichtigen IDs.

• grc_evidence_mcp/server.py – MCP-Tool-Registrierung und Evidence-Speicher-Workflow.

• grc_evidence_mcp/github.py – schreibgeschützter GitHub-API-Evidence-Collector.

• grc_evidence_mcp/screenshot.py – optionaler Playwright-Screenshot-Collector.

• .env.example – sichere Vorlage für die GitHub-Token-Variable.

• .gitignore – verhindert, dass lokale Geheimnisse wie .env committet werden.

• pyproject.toml – Python-Abhängigkeiten und optionale Screenshot-Erweiterung.

Kern-Tools:

• list_evidence_sources

• collect_evidence

• get_evidence_collection

Optionaler Bonus-Tool:

• collect_visual_evidence

Fehlerbehebung nach Symptom

Befehl claude nicht gefunden

Installiere Node.js falls nötig und führe dann die Claude-Code-npm-Installation erneut aus.

MCP-Tool erscheint nicht in Claude Desktop

Überprüfe den Konfigurationsort und den vollständigen Serverpfad, bestätige, dass der Server im Terminal startet, starte Claude Desktop vollständig neu und öffne dann einen neuen Chat.

GITHUB_TOKEN is not set

Bestätige, dass .env im Projektstamm existiert, GITHUB_TOKEN=... enthält und du das aktualisierte Projekt ausführst, das .env lädt. Starte Claude Desktop nach Änderungen an Umgebung/Konfiguration neu.

GitHub gibt 401 zurück

Das Token ist ungültig, abgelaufen oder wird nicht korrekt gelesen.

GitHub gibt 403 zurück

Das Token/Konto hat wahrscheinlich nicht den erforderlichen Lesezugriff auf das Repository oder die Einstellungen.

GitHub gibt 404 zurück

Bezeichne es nicht sofort als Kontrollfehler. Bestätige das Repository, den Branch, den Token-Zugriff und die zugrunde liegende GitHub-Antwort.

Playwright ist nicht installiert

Führe aus:

pip install -e ".[screenshot]"
playwright install chromium

Screenshot zeigt eine Anmeldeseite

Das ist immer noch ein echter Screenshot, beweist aber nicht den Kontrollzustand. Behandle ihn als unbestimmt und authentifiziere dich angemessen, bevor du es erneut versuchst, wenn du dazu berechtigt bist.

Bevor du dein Repository veröffentlichst

• Stelle sicher, dass .env nicht committet wird.

• Durchsuche das Repository nach deinem Token oder anderen Geheimnissen.

• Behalte den Abschnitt zu Einschränkungen in der README bei.

• Erkläre, dass die GitHub-Aufrufe schreibgeschützt sind.

• Erkläre, dass Screenshots den Seitenzustand zum Zeitpunkt der Aufnahme zeigen, nicht die Wirksamkeit der Kontrolle.

• Füge ausreichend Einrichtungsanweisungen hinzu, damit eine andere Person den Build reproduzieren kann.

• Verwende in Screenshots/Beispielen dein eigenes Repository oder schwärze alles, was du nicht veröffentlichen solltest.

Für die Herausforderung

Um das Erreichen von 100 Abonnenten zu feiern: ein 306-Dollar-Gewinnspiel – ein Jahr Claude Pro plus ein Jahr GRC Engineering Club-Mitgliedschaft.

Um teilzunehmen:

1. Sei abonniert.

2. Baue den MCP.

3. Reiche das GitHub-Repository für das ein, was du gebaut hast.

Ein Gewinner wird per Zufallsziehung aus den qualifizierten Einsendungen ausgewählt. Markiere dein Projekt mit Built with BuildinginGRC.

Abschließender Lerncheck

Bevor du das Projekt als abgeschlossen bezeichnest, solltest du diese fünf Dinge in eigenen Worten erklären können:

1. Warum der MCP gegenüber dem geprüften System schreibgeschützt ist.

2. Warum der Server Beweise speichert und eine collection_id zurückgibt, anstatt alles direkt zurückzugeben.

3. Warum das GitHub-Token nur die Berechtigungen haben sollte, die der Collector benötigt.

4. Warum eine 404- oder Login-Wand nicht automatisch ein Beweis dafür ist, dass eine Kontrolle fehlt.

5. Was ein API-Ergebnis beweist im Vergleich zu dem, was ein Screenshot beweist.

Wenn du diese erklären kannst, hast du mehr getan, als ein Projekt zu kopieren – du verstehst die GRC-Engineering-Entscheidungen dahinter.