Mcp Audit Skill

mcp-audit-skill

> Claude-Skill für systematische Audits von MCP-Servern gegen einen kuratierten Best-Practice-Standards-Korpus. 68 Checks, 8 Kategorien, mit Schweiz-Compliance-Layer für die öffentliche Verwaltung.

[](./LICENSE) [](./checks/) [](./CHANGELOG.md) [](https://modelcontextprotocol.io/specification/)

---

Was es ist: Ein Claude-Skill, der MCP-Server systematisch gegen veröffentlichte Best Practices auditiert. Jeder Check referenziert seine Quelle, hat klare Pass-Kriterien, einen Remediation-Pfad und einen Aufwands-Indikator.

Was es nicht ist: Kein automatischer Code-Scanner, kein Vulnerability-Tool, kein Compliance-Stempel. Der Skill macht die Methodik reproduzierbar — Architektur-Urteile bleiben menschlich.

Architektur-Modell

Die Checks orientieren sich am Fünf-Schichten-Sicherheitsmodell, das in der MCP-Sicherheits-Community als Konsens-Architektur etabliert ist. Jede Schicht prüft eigenständig — keine vertraut der nächsthöheren blind.

┌────────────────────────────────────────────────────────┐
│  LLM-Host (Claude, ChatGPT, Cursor)                    │
│  Untrusted: kann Prompt-Injektionen enthalten          │
└────────────────────────┬───────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────┐
│  MCP-Gateway / Policy Layer                            │
│  Rate-Limit · Audit-Log · DLP · Tool-Allowlist         │
└────────────────────────┬───────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────┐
│  Authentifizierung & Autorisierung                     │
│  OAuth 2.1 + PKCE · Resource Indicators · Scopes       │
└────────────────────────┬───────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────┐
│  MCP-Server-Logik                                      │
│  Input-Validierung · Schema · Idempotenz · Sandbox     │
└────────────────────────┬───────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────┐
│  Datenquelle / Backend                                 │
│  Read-only Service-Account · Least Privilege           │
└────────────────────────────────────────────────────────┘

SOLID für MCP-Server

Die fünf Prinzipien, an denen sich der gesamte Check-Katalog ausrichtet:

| Prinzip | Bedeutung | Schlüssel-Checks | |---|---|---| | Sandbox | Jeder Server in Docker / WASM mit Egress-Filter | [SEC-007](./checks/SEC-007.md), [SEC-021](./checks/SEC-021.md) | | OAuth 2.1 | OAuth statt API-Keys, mit PKCE und Resource Indicators | [SEC-001](./checks/SEC-001.md), [SEC-002](./checks/SEC-002.md), [SEC-003](./checks/SEC-003.md) | | Least Privilege | Service-Account-Rechte minimal halten | [SEC-003](./checks/SEC-003.md), [SEC-013](./checks/SEC-013.md) | | Idempotency | Idempotency-Keys + Compensating Actions bei jedem Write | [ARCH-010](./checks/ARCH-010.md) | | Defense-in-Depth | Gateway + Auth + Schema + Sandbox + DLP gestapelt | [SCALE-005](./checks/SCALE-005.md), [SEC-018](./checks/SEC-018.md), [SEC-023](./checks/SEC-023.md) |

Wer alle fünf abdeckt, ist gegen ~80% der heute beobachteten Angriffsklassen geschützt. Die übrigen ~20% — primär Prompt-Injection auf Tool-Description-Ebene — sind strukturell ungelöst und brauchen organisatorische Kontrollen (Human-in-the-Loop, Threat Detection, Audit-Reviews).

Anchor-Demo

> «Erfüllt mein parlament-mcp-Server alle 23 Security-Checks für eine Phase-1-Read-only-Anbindung an Stadt-Zürich-Verwaltungsdaten?»

Mit installiertem Slash-Command:

> /audit-mcp .

Output: Profil-getriebene Auswahl der ~30 anwendbaren Checks aus 68, automatisierte Verifikation aller automated/config_check/documentation_check-Modi, Findings-Stubs für code_review/runtime_test-Modi, vollständiger Audit-Report nach Template — alles in /audits/YYYY-MM-DD-/.

Standards-Provenance

Die 68 Checks sind systematische Übersetzungen aus zwei kuratierten Best-Practice-Dokumenten in auditierbare Form. Jeder Check trägt im Frontmatter eine pdf_ref-Referenz auf seine Quelle.

| Quelle | Inhalt | Abgeleitete Checks | |---|---|---| | Hauptkatalog «MCP Server-Entwicklung — Best Practices & Standards» | Architektur, SDK-Patterns, Security, Skalierung, Observability, Human-in-the-Loop | 54 Checks (v0.1–v0.4) | | Architektur-Anhang «Architektur und Sicherheit von MCP-Servern» | Sektion A (Architektur, A1–A9), Sektion B (Sicherheit, B1–B12), Sektion C (Operative Praxis, C1–C4); schliesst u.a. Lethal-Trifecta-, Idempotency- und Egress-Control-Lücken | 14 Checks (v0.5) | | Schweiz-Compliance-Layer | revDSG, EDÖB-Meldepflicht, ISDS Stadt Zürich, OGD-Lizenz-Compliance, Volksschule-spezifische Datenschutz-Anforderungen | 8 Checks (CH-*) |

Schnellstart

Voraussetzungen — Cross-Platform

| Betriebssystem | Voraussetzung | |---|---| | Linux / macOS | Python 3.11+, Bash, git, yq | | Windows (Git Bash) | Python 3.11+ mit PYTHONUTF8=1, Git Bash, git, yq |

Windows-User: Setze die Env-Var PYTHONUTF8=1 in deinem Profil (oder pro Session), sonst crasht Python beim Schreiben von Umlauten/Emojis:

# PowerShell
[Environment]::SetEnvironmentVariable("PYTHONUTF8", "1", "User")

# Git Bash
echo 'export PYTHONUTF8=1' >> ~/.bashrc

Pfad-Helpers für Skill-Scripts liegen unter [tools/paths.sh](tools/paths.sh) (Bash) und [tools/path_utils.py](tools/path_utils.py) (Python). Sie konvertieren zwischen /c/Users/foo (Git Bash) und C:\Users\foo (Windows-native, was die Read/Edit/Write-Tools brauchen).

Als Claude-Code-Slash-Command (/audit-mcp)

Der Skill bringt einen Slash-Command mit, der den 6-Schritte-Workflow als Claude-Code-Workflow ausführt — Profil-Load, Applicability-Filter, automatisierte Check-Ausführung, Findings-Generierung und Report-Erstellung in einem Lauf.

git clone https://github.com/malkreide/mcp-audit-skill.git
cd mcp-audit-skill
./setup-slash-command.sh

Das Setup-Script symlinkt .claude/commands/audit-mcp.md nach ~/.claude/commands/, damit /audit-mcp global in jeder Claude-Code-Session verfügbar ist.

Verwendung:

# In einem MCP-Server-Repo oder beliebigen Verzeichnis
claude

> /audit-mcp .
> /audit-mcp /pfad/zum/server-repo
> /audit-mcp https://github.com/malkreide/zh-education-mcp

Output landet in /audits/YYYY-MM-DD-/ mit:

• audit-report.md — Gesamtreport nach Template
• findings/-*.md — pro Fail/Partial-Check ein Finding
• raw/.txt — Roh-Output der Bash-Befehle für Audit-Trail

Automatisierungstiefe ist Standard: alle automated/config_check/documentation_check-Modi laufen automatisch, code_review/runtime_test-Modi werden als TODO mit Such-Pattern in den Report geschrieben (kein Pattern-Match-Halluzinieren).

Portfolio-Batch-Audit (audit-portfolio.sh)

Wenn du mehrere MCP-Server in einem Run auditieren willst, nutze das Top-Level-Script audit-portfolio.sh. Es liest deine portfolio.yaml (Server-Liste mit Profil pro Server), klont jedes Repo, ruft claude -p mit dem /audit-mcp-Slash-Command non-interactive auf und aggregiert die Findings in eine portfolio-summary.md.

cp portfolio.example.yaml portfolio.yaml
$EDITOR portfolio.yaml          # deine Server-Liste anpassen
./audit-portfolio.sh --dry-run  # Plan verifizieren, kein claude-Call
./audit-portfolio.sh            # echter Run, alle Server sequenziell
./audit-portfolio.sh zh-education-mcp foo-mcp   # Subset
./audit-portfolio.sh --force    # auch heute schon auditierte Server neu

portfolio.yaml ist .gitignored — committe deine Server-Liste nicht versehentlich. Dependencies: yq (Mike Farahs Go-yq oder kislyuks Python-yq + jq), git, claude CLI. Output landet in portfolio-logs//.

Notion-Sync (audit-notion-sync.py) — bidirektionale Tracker-Integration

Wenn dein Audit-Tracker in Notion lebt, nutze audit-notion-sync.py für bidirektionale Synchronisation: Pull generiert portfolio.yaml aus dem Tracker, Push schreibt Findings-Anzahl und Audit-Status nach jedem Lauf zurück. Stdlib-only, kein pip install nötig.

Einmaliges Setup:

1. In Notion: Tracker → ••• → Connections → + Add connections → deine Internal Integration auswählen
2. Im Tracker eine neue Property anlegen: Name Org-Kontext, Type Multi-select, Optionen Stadt Zürich, Schulamt, Volksschule, Enterprise — dann pro Server ankreuzen, was zutrifft
3. Token in deine Shell-RC (niemals committen):

``bash export NOTION_TOKEN="ntn_..." ``

1. Verifizieren:

``bash python3 audit-notion-sync.py health ``

Verwendung:

# Nur Pull (Tracker → portfolio.yaml)
python3 audit-notion-sync.py pull --force
./audit-portfolio.sh

# Oder kombiniert: Pull, Audit, Push in einem Run
./audit-portfolio.sh --from-notion --sync-back

Der Pull filtert standardmässig auf Server mit Audit-Status ∈ {Triagiert, In Audit} — --all ignoriert den Filter. Der Push setzt Findings (number), Audit-Status (auf Findings dokumentiert) und appendet eine Notiz mit dem Report-Pfad. Formula-Felder (Risiko-Score, Reife-Score, Prio) bleiben unangetastet.

Die DB-ID ist als Default auf a2736a65-677d-4cf3-9f94-e874f74a1975 (Stadt Zürich Schulamt MCP Audit Tracker) gesetzt; NOTION_AUDIT_DB_ID env var überschreibt.

Als Claude.ai-Skill (manuell)

git clone https://github.com/malkreide/mcp-audit-skill.git ~/skills/mcp-audit

Dann in Claude.ai: Verwende mcp-audit-Skill für . Der Workflow läuft dann interaktiv ohne Slash-Command-Automatisierung.

Check-Katalog im Überblick

| Code | Bereich | Quelle | Anzahl | Severity-Profil | |---|---|---|---:|---| | ARCH | Tool-Design, Annotations, Idempotency, Repo-Struktur, Spec-Versionierung | Hauptkatalog Sec 2 + Anhang A | 12 | 1 critical · 7 high · 4 medium | | SDK | FastMCP, TypeScript, Zod, Lifecycle | Hauptkatalog Sec 3 | 5 | — · 3 high · 2 medium | | SEC | Security (grösste Kategorie) | Hauptkatalog Sec 4 + Anhang B | 23 | 14 critical · 8 high · 1 medium | | SCALE | Transport, Load Balancing, Container, Gateway | Hauptkatalog Sec 5 | 6 | — · 3 high · 3 medium | | OBS | Logging, Errors, SIEM, OpenTelemetry | Hauptkatalog Sec 6 + Anhang B10 | 6 | 1 critical · 1 high · 4 medium | | HITL | Sampling, Human-in-the-Loop | Hauptkatalog Sec 7 | 5 | 1 critical · 4 high · — | | CH | DSG/EDÖB, ISDS Stadt Zürich, Volksschule | Custom | 8 | 3 critical · 4 high · 1 medium | | OPS | Test-Strategie, Doku-Standard, Phasenarchitektur | Anhang C | 3 | — · 2 high · 1 medium | | Total | | | 68 | 15 critical · 31 high · 22 medium |

Severity-Stufen

| Stufe | Bedeutung | Konsequenz | |---|---|---| | critical | Sicherheitslücke / Compliance-Bruch | Blockiert Produktion | | high | Architektureller Mangel mit signifikantem Risiko | Im laufenden Sprint fixen | | medium | Best-Practice-Verletzung | Im nächsten Sprint planen | | low | Polish, Optimierung | Backlog |

Audit-Workflow (Kurzform)

1. Profil laden — Server-Eigenschaften aus Notion-Audit-Tracker oder via Inferenz aus dem Repo
2. Katalog laden — alle 68 Checks parsen
3. Applicability-Filter — nur passende Checks selektieren (z.B. stdio-only-Server überspringt OAuth-Checks)
4. Check-Ausführung — automatisiert (grep, AST, Config-Scan) oder als Code-Review-TODO pro Check
5. Findings dokumentieren — templates/finding.md
6. Audit-Report — templates/audit-report.md

Details siehe [SKILL.md](./SKILL.md).

Positionierung gegenüber verwandten Tools

| Tool | Kategorie | Fokus | |---|---|---| | apisec-inc/mcp-audit | Code-Scanner | Lokale MCP-Configs (Secrets, Shadow-APIs, AI-BOM, SARIF) | | ModelContextProtocol-Security/mcpserver-audit (CSA) | Tutorial-Tool | Lehrt CWE/AIVSS-Methodik anhand von Beispiel-Servern | | qianniuspace/mcp-security-audit | Dependency-Scanner | npm-Vulnerability-Scan für MCP-Pakete | | malkreide/mcp-audit-skill | Audit-Framework | Systematische Prüfung gegen kuratierten Best-Practice-Korpus + CH-Compliance |

Komplementär nutzbar — keiner der Genannten ersetzt die anderen.

Verwandte Repos

• malkreide MCP-Server-Portfolio — die Server, gegen die dieses Skill auditiert wird
• Notion MCP Audit Tracker — laufender Status aller Server-Audits (intern)
• Notion MCP Server Portfolio — Master-Inventar aller Server (intern)

Status

Version: v1.0.0 — Production-Ready Reproducibility (10 Helper-Scripts, 255 pytest cases, CI auf Ubuntu + Windows × py3.11 + py3.13). Siehe [CHANGELOG.md](./CHANGELOG.md) für die vollständige Release-History.

Vollständigkeit:

• ✅ Methodik (SKILL.md) und Templates (Finding, Audit-Report)
• ✅ Reference-Summary
• ✅ Check-Katalog: 68 Checks, alle 8 Kategorien vollständig
• ✅ Slash-Command für Claude Code (/audit-mcp )
• ✅ Portfolio-Batch-Audit (audit-portfolio.sh für Multi-Server-Runs)
• ✅ Notion-Sync (audit-notion-sync.py für bidirektionale Tracker-Integration)
• ✅ Vollständige Abdeckung beider Standards-Quellen (Hauptkatalog + Architektur-Anhang)

Künftige Erweiterungen kommen aus Real-World-Findings beim Portfolio-Audit, MCP-Spec-Updates oder neuen Compliance-Anforderungen (EU AI Act, Schweizer KI-Gesetz). Versions-Roadmap siehe [docs/roadmap.md](./docs/roadmap.md).

Lizenz

MIT — siehe [LICENSE](./LICENSE).

Kontext

Entwickelt im Rahmen des Swiss Public Data MCP Portfolio. Frei verwendbar von anderen Verwaltungen, Forschungsinstituten oder Privatpersonen, die MCP-Server systematisch auditieren wollen.

Pull Requests willkommen — insbesondere für ergänzende Compliance-Layer anderer Jurisdiktionen (DSGVO-Spezifika, kantonale Datenschutzgesetze, sektorspezifische Vorgaben).

---

Autor: Hayal Oezkan

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: malkreide
• Source: malkreide/mcp-audit-skill
• License: MIT
• Homepage: https://github.com/malkreide/swiss-public-data-mcp

Install and usage instructions live in the source repository linked above.