mcp-doorman

Das Sicherheits-Gateway für MCP-Server – jeder Tool-Aufruf wird an der Tür geprüft.

CI npm License: Apache-2.0 PRs welcome

mcp-doorman ist ein Drop-in-Proxy, der sich zwischen Ihren KI-Agenten (Claude Desktop, Claude Code, Cursor, VS Code, jeder MCP-Client) und die von ihm genutzten MCP-Server setzt. Ein Befehl, keine Infrastruktur, und jeder tools/list- und tools/call-Aufruf durchläuft eine Schutz-Pipeline:

• 🛂 Policy-Engine – Erlauben/Verweigern/Genehmigung erforderlich-Regeln pro Tool, Glob-Matching
• 🕵️ Geheimnis-Schwärzung – AWS-Keys, GitHub/Slack/Stripe/OpenAI/Anthropic-Tokens, private Schlüssel, JWTs, Karten (Luhn-geprüft)… aus Tool-Ergebnissen bevor sie das Modell erreichen, entfernt
• 💉 Prompt-Injection-Screening – kennzeichnet oder blockiert Tool-Ergebnisse (und Tool-Beschreibungen – Tool-Poisoning), die versuchen, das Modell zu instruieren
• 📌 Rug-Pull-Erkennung – Tool-Definitionen werden bei erster Nutzung per Hash gepinnt; wenn ein Server stillschweigend eine Beschreibung austauscht, wird das Tool blockiert, bis ein Mensch es neu pinnt
• 🚦 Ratenbegrenzung – Token-Buckets pro Tool begrenzen die Schadensreichweite einer außer Kontrolle geratenen Agenten-Schleife
• 🙋 Menschliche Genehmigungs-Gates – sensible Tools lösen eine interaktive Genehmigungsaufforderung via MCP-Elicitation direkt in Ihrem Client aus
• 🧾 Audit-Log – jeder Aufruf, jede Verweigerung, Schwärzung und Markierung landet in einer append-only JSONL-Datei

Warum es das gibt

Jeder ist nur einen npx some-random-mcp-server davon entfernt, einem ungeprüften Prozess seine API-Schlüssel und eine direkte Leitung in das Kontextfenster seines Modells zu übergeben. Die dokumentierten Angriffsklassen sind real, nicht hypothetisch:

Enterprise-MCP-Gateways gibt es für Plattform-Teams mit Kubernetes-Clustern. Nichts Leichtes schützt den Laptop des einzelnen Entwicklers – den Ort, an dem 99% der MCP-Server tatsächlich laufen. Diese Lücke schließt dieses Projekt.

Schnellstart (60 Sekunden)

# 1. Create a config
npx -y mcp-doorman init

# 2. Edit doorman.config.json — put your real servers in it

# 3. Pin the current tool definitions (trust on first use)
npx -y mcp-doorman pin --config doorman.config.json

Richten Sie dann Ihren Client auf das Gateway anstelle Ihrer Server. Claude Desktop / Claude Code / Cursor:

// BEFORE — every server talks straight to the model
{
  "mcpServers": {
    "github":     { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/repos"] }
  }
}

// AFTER — one doorman guards them all
{
  "mcpServers": {
    "doorman": {
      "command": "npx",
      "args": ["-y", "mcp-doorman", "run", "--config", "/absolute/path/to/doorman.config.json"]
    }
  }
}

Tools erscheinen namespace-gescoped als github__create_issue, filesystem__read_file, usw., plus zwei Built-ins: doorman__status und doorman__recent_events (fragen Sie Ihren Agenten "Was hat doorman kürzlich blockiert?").

Windows-Hinweis: Wenn ein Server-Eintrag direkt npx verwendet, starten Sie ihn über cmd: "command": "cmd", "args": ["/c", "npx", "-y", "..."].

In Aktion sehen

git clone https://github.com/Sushank05/mcp-doorman && cd mcp-doorman
npm install
npm run demo

Die Demo verbindet das Gateway mit einem absichtlich fehlverhaltenden Server (examples/demo-server.mjs), der gefälschte Zugangsdaten preisgibt, eine Prompt-Injection-Nutzlast ausliefert und ein zerstörerisches Tool anbietet – und zeigt, wie jede Schutzmaßnahme es abfängt.

Wie es funktioniert

flowchart LR
    A["MCP client\n(Claude Desktop, Cursor, ...)"] -- stdio --> D
    subgraph D [mcp-doorman]
        direction TB
        P[policy] --> R[rate limit] --> AP[approval] --> RD[redaction] --> I[injection scan] --> AU[(audit log)]
    end
    D -- stdio --> S1[github server]
    D -- stdio --> S2[filesystem server]
    D -- streamable HTTP --> S3[remote server]

Das Gateway ist ein MCP-Server gegenüber Ihrem Client und ein MCP-Client gegenüber jedem Upstream (stdio-Kindprozesse oder streamable-HTTP-Endpunkte), die hinter einer Verbindung aggregiert werden. Es basiert auf dem offiziellen TypeScript SDK.

Konfiguration

Alles lebt in einer JSON-Datei. Vollständiges Beispiel mit jeder Option:

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }   // ${VAR} = read from gateway env
    },
    "remote": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${MCP_TOKEN}" } }
  },

  "policy": {
    "defaultAction": "allow",                    // "allow" | "deny" | "approve"
    "rules": [                                   // first match wins, evaluated top-down
      { "match": "*__delete*",  "action": "deny",    "reason": "no destructive tools" },
      { "match": ["github__create_*", "*__send_*"], "action": "approve" },
      { "match": "filesystem__*", "action": "allow" }
    ]
  },

  "redaction": {
    "enabled": true,
    "disable": [],                               // built-in rule names to turn off
    "enableOptIn": ["email"],                    // opt-ins: "email", "us-ssn", "ipv4"
    "custom": [{ "name": "acme-id", "pattern": "ACME-[0-9]{6}" }],
    "redactArguments": false                     // also scrub model-supplied arguments
  },

  "injection": {
    "action": "flag",                            // "flag" (warn the model) | "block" | "off"
    "scanToolDescriptions": true,                // tool-poisoning check on tools/list
    "custom": []
  },

  "pinning": {
    "enabled": true,
    "onNewTool": "pin",                          // "pin" (TOFU) | "block" (until `mcp-doorman pin`)
    "onChangedTool": "block"                     // "block" | "warn"
  },

  "rateLimit": { "perMinute": 120, "perTool": { "*__send_*": 5 } },

  "approval": { "fallback": "deny", "timeoutMs": 120000 },  // fallback when client lacks elicitation

  "audit": { "enabled": true, "includeArguments": true, "includeResults": false },

  "logLevel": "info"
}

Pin-Zustand und Audit-Log standardmäßig in <config-name>.pins.json / <config-name>.audit.jsonl neben der Konfigurationsdatei.

CLI

Ehrliche Einschränkungen

Sicherheitstools, die übertreiben, sind schlimmer als gar keine. Lesen Sie diesen Teil.

• Heuristiken sind umgehbar. Die Injection-Muster erkennen dokumentierte, gängige Angriffsformen. Ein motivierter Angreifer kann jedes Regex umgehen. Verwenden Sie deny/approve-Richtlinien als harte Grenze; Screening ist Defense-in-Depth.
• Schwärzung ist nach bestem Bemühen. Bekannte Token-Formate werden zuverlässig erkannt; ein zufälliges Hex-Geheimnis ohne Kontext nicht. Richten Sie Agenten nicht auf Credential-Stores.
• Dies ist keine Sandbox. Upstream-Server laufen weiterhin als Kindprozesse mit den Privilegien Ihres Benutzers. Doorman schützt das Protokoll; kombinieren Sie es mit Containern (ToolHive-Stil), um den Prozess zu schützen.
• TOFU vertraut dem ersten Anblick. Pinning erkennt Änderungen, nicht Tools, die von Anfang an bösartig waren – dafür sind der Beschreibungs-Scanner und Ihre eigene Überprüfung da.
• Genehmigungs-Gates benötigen Elicitation. Clients ohne Elicitation-Support fallen auf approval.fallback zurück (standardmäßig verweigern).

Roadmap – Hilfe gesucht 🙌

• resources/*- und prompts/*-Proxying (derzeit nur Tools)
• Durchleitung für Sampling und Roots
• Community-Regelpakete (doorman-rules-finance, doorman-rules-healthcare…)
• Lernmodus: eine Woche beobachten, ein Least-Privilege-Policy vorschlagen
• OPA / Cedar-Policy-Backends
• mcp-doorman audit-Unterbefehl: JSONL-Log hübsch ausgeben und abfragen
• Web-Dashboard zur Audit-Visualisierung
• Entropie-basierte generische Geheimnis-Erkennung

Schnappen Sie sich etwas aus der Liste oder beginnen Sie mit einem [good first issue](https://github.com/YOUR_GITHUB_USERNAME/mcp-doorman/labels/good%20first%20issue). Neue Erkennungsregeln sind der einfachste Beitrag: ein Regex + zwei Tests. Siehe CONTRIBUTING.md und docs/detection-rules.md.

Entwicklung

npm install
npm test          # 69 tests: unit + full stdio e2e
npm run build
npm run demo      # watch the guards fire live

Lizenz

Apache-2.0 – kostenlos für jede Nutzung, mit einer ausdrücklichen Patentgewährung.