Inventarisiert und bewertet lokale MCP server nach Risikostufen, indem sie diese über verschiedene Konfigurationsdateien und laufende Prozesse hinweg identifiziert.
Auch bekannt als saagpatel/shadow-mcp
- Stars
- 0
- Tools
- 4
- Downloads, 30 Tage
- 100
- Neueste Version
- 0.2.0
- Letzter Commit
- 14. Nov. 2026
- Lizenz
- —
Was ist shadow MCP?
shadow ist ein MCP server. Inventarisiert und bewertet lokale MCP server nach Risikostufen, indem sie diese über verschiedene Konfigurationsdateien und laufende Prozesse hinweg identifiziert. Er stellt 4 Tools bereit, etwa scan_local, discover_local, deep_scan.
Zusammenfassung generiert aus dem README des Projekts
Über shadow MCP server
Security Researcher und Entwickler können shadow-mcp nutzen, um die Sicherheitslage von MCP servern zu identifizieren und zu bewerten, die auf einer lokalen Maschine laufen. Es löst das Problem von Shadow-MCP-Servern, indem es Konfigurationen findet, die über Claude Code, Claude Desktop, Codex, projektspezifische .mcp.json Dateien und laufende Prozesse, die keinen Port binden, verstreut sind. Das Tool erstellt ein vollständiges Inventar, indem es Funde aus verschiedenen Quellen zu einer einzigen logischen Ansicht deiner lokalen Umgebung zusammenführt.
Nach dem Discovery weist das System Risikostufen zu, indem es die Analyse an spezialisierte Engines wie MCPAudit für die Bewertung von Capabilities und Injection-Schwachstellen sowie mcp-trust für die Einstufung von Gefahren delegiert. Nutzer können einen statischen Scan basierend auf Konfigurationsdateien durchführen oder sich für einen vernetzten Deep-Scan entscheiden, der tatsächlich stdio Server startet, um die realen Tools zu enumerieren. Die Ergebnisse werden in Form von Terminal-Tabellen, maschinenlesbarem JSON oder Markdown-Reports bereitgestellt und zeigen Diskrepanzen zwischen konfigurierten und laufenden Servern auf.
Was du damit machen kannst
- 1Lokale Server-Konfigurationen auditierenIdentifiziere alle MCP server, die in verschiedenen Konfigurationsdateien und aktiven Prozessen auf deinem Rechner versteckt sind.
- 2Reale Tool-Capabilities bewertenFühre einen Deep-Scan durch, der eine Verbindung zu den Servern herstellt, um deren tatsächliche funktionale Berechtigungen zu prüfen.
- 3Maschinenlesbare Security-Inventare erstellenExportiere ein vollständiges Inventar deiner lokalen MCP-Fläche als JSON-Datei für die automatisierte Verarbeitung.
- 4Präsenz von Shadow-Servern überwachenErkenne Server, die aktuell laufen, aber nicht in deinen Standard-Konfigurationsdateien dokumentiert sind.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du shadow MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügenshadow MCP in Claude Code installieren
$ claude mcp add shadow-mcp -- uvx shadow-mcpshadow MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}shadow MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"shadow-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}shadow MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"shadow-mcp","type":"stdio","command":"uvx","args":["shadow-mcp"]}'shadow MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}shadow MCP in Codex installieren
$ codex mcp add shadow-mcp -- uvx shadow-mcpshadow MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.shadow-mcp] command = "uvx" args = ["shadow-mcp"]
shadow MCP in Gemini CLI installieren
$ gemini mcp add -s user shadow-mcp uvx -- shadow-mcpshadow MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}shadow MCP tools 4
Erkannt aus dem READMEscan_localdiscover_localdeep_scanlist_sources
| scan_local | — | |
| discover_local | — | |
| deep_scan | — | |
| list_sources | — |
Automatisierte Checks
Geluften am 14. Nov. 2026Vollständiger Bericht →Unsere automatisierten Checks bestanden. Das ist kein Security-Audit: Lies den Code und gib dem Server nur den minimal notwendigen Zugriff. Wie die Checks funktionieren · Was du für mehr Punkte verbessern kannst
- Source Repository verknüpft und erreichbarsaagpatel/shadow-mcp is public and reachablegithub.com/saagpatel/shadow-mcp ↗Bestanden
- Paket nennt dieses Repository als QuelleNicht geprüft
- Build-Provenienz (Sigstore-Attestierung)Sigstore attestation for shadow-mcppypi.org/project/shadow-mcp/ ↗Bestanden
- Open Source Lizenz (OSI)No licenseBefund
- Commit oder Release im letzten JahrLast commit or release 2026-11-08github.com/saagpatel/shadow-mcp ↗Bestanden
- OpenSSF ScorecardNicht geprüft
- Package-Name ähnelt keinem populären PackageNo popular package one edit away from shadow-mcpBestanden
- Keine kritischen Advisories im Paket oder seinen Abhängigkeiten43 resolved dependencies checked; no critical advisoryosv.dev ↗Bestanden
- Keine versteckten Anweisungen an das Modell4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersBestanden
- Destruktive Tools sind markiertNo tool named like delete, drop or execBestanden
- Remote-Endpoint beantwortet den MCP-HandshakeNicht geprüft
README
Auf GitHub ansehenshadow-mcp
Discover and risk-grade the MCP servers actually present on this machine.
Most MCP security tooling assumes you already have a list of servers to audit.
On a real developer machine you don't: servers are scattered across Claude Code,
Codex, Claude Desktop, project-local .mcp.json files, DXT extensions, and live
processes that bind no port. shadow-mcp finds them first, then grades them.
This is the local-first answer to OWASP MCP09:2025 — Shadow MCP Servers.
What it does
discover -> inventory -> risk-grade -> report
- Discover (read-only) MCP servers from supported configuration and runtime sources:
Claude Code (
~/.claude.json, user + project scope),claude mcp list(catches remote + plugin servers no file contains), Codex (~/.codex/config.toml+ profiles), project.mcp.json, Claude Desktop config + DXT extension manifests, and the live process table. - Inventory: merge sightings into one entry per logical server, even when a
server appears under different names across hosts (
personal-opsvspersonal_ops), tracking every provenance. - Risk-grade by delegating to the existing engines rather than reimplementing them:
- Report: a ranked terminal table, a machine-readable JSON inventory, or markdown — plus a Shadow & attention section for the deltas that matter (running-but-unconfigured, broad blast radius, capable-but-ungraded).
The risk model and its OWASP mapping live in docs/risk-model.md.
Install
From this repository root, use uv:
make setup
The grading engines (mcp-audits and mcp-trust) are runtime dependencies
resolved from PyPI, not editable sibling checkouts or an engines group.
The installed mcp-trust package supplies its seed catalog; --registry-db or
SHADOW_MCP_MCPTRUST_DB selects an explicitly chosen local registry instead.
Use
uv run shadow-mcp scan # full pipeline, terminal report
uv run shadow-mcp scan --json out.json # machine-readable inventory
uv run shadow-mcp scan --format markdown # markdown report
uv run shadow-mcp discover # inventory only, no grading
uv run shadow-mcp sources # per-collector counts
uv run shadow-mcp grade-missing # A-F for servers the registry hasn't scanned
uv run shadow-mcp deep-scan cost-tracker # connect to a server, grade its real tools
Useful flags: --no-processes (skip the live process scan), --no-cli (skip
claude mcp list), --no-mcpaudit (inventory + mcp-trust only), --home PATH
(point discovery at a fixture tree).
Static vs connected grading
By default grading is static (config-only): no server is spawned, so grades reflect what's visible in the config. That's safe but coarse — a server's real capability only shows once you connect and list its tools.
shadow-mcp scan --connect (or deep-scan [names...]) spawns each stdio
server and enumerates its real tools, delegating to MCPAudit's connected engine
for a capability grade that actually differentiates (a filesystem server jumps
from a static A to a connected D). This is opt-in because connecting
executes the server; remote endpoints are never spawned (that's the network-scan
tier), and a server that needs real secrets to start falls back to its static
grade.
Development and safe verification
The committed uv.lock fixes the PyPI runtime and development graph. From the
repository root, run:
make check
The suite uses synthetic homes. Keep SHADOW_MCP_RUN_CONNECT unset: the
explicitly opted-in connected test is a separate server-execution lane. CI runs
the same aggregate gate on Python 3.11 through 3.15; see
the workflow. make build creates the wheel and
sdist used by the release workflow.
Do not use the normal scan, discover, sources, grade-missing or MCP tool
calls as a development smoke: they inventory the machine by default. CLI
deep-scan and scan --connect additionally execute servers. For changed JSON
or Markdown reports, check the corresponding fixture tests (tests/test_report.py)
and inspect synthetic output; this CLI has no browser UI. Actual workstation or
connected behavior requires its own explicitly authorized qualification.
Safety
- Read-only discovery. Collectors parse configs, invoke
claude mcp list(unless--no-cliis set), and list processes; nothing they find is ever mutated. (--connect/deep-scanis the one path that executes servers, and only when you explicitly ask.) - Secrets stay out. We record env variable names (to flag secret-bearing
servers per MCP01) but never their values. Inline credentials in command
arguments, URLs, and process parent commands are redacted before storage. A
captured inventory still contains local paths and hostnames, so treat
*.inventory.jsonas private (it is git-ignored by default).
Use as an MCP server
shadow-mcp can serve its own inventory tools as an MCP server so an agent can query your local MCP surface without leaving the conversation.
Tools
| Tool | Description |
|---|---|
scan_local |
Full pipeline (discover → inventory → grade → report). Returns JSON. |
discover_local |
Inventory every MCP server without grading. Returns JSON. |
deep_scan |
Grade the named servers, or all servers when the list is empty (static, no spawning). Accepts names: list[str]. Returns JSON. |
list_sources |
Per-collector source counts from a discover run. Returns JSON. |
Run the server
# directly from a local checkout
uv run shadow-mcp mcp-serve
# via uvx (once published to PyPI)
uvx shadow-mcp mcp-serve
LOCAL only. MCP tools read local configs and the process table, skip
claude mcp list, and never connect to hosted MCP endpoints or spawn servers.
Grading is static (config-based); connect=False is enforced unconditionally.
Scope
This is the local-first tool: it inventories one machine from its configs
and processes. A later network-scan expansion (probing hosts/ports for remote
MCP endpoints, org-wide fleet inventory, typosquat-distance provenance checks)
is deliberately out of scope here — see the bottom of docs/risk-model.md and
the project notes for what that would add.
Status
Stack
Python 3.11+; uv-managed locked dependencies; Ruff, mypy, and pytest checks; Hatchling wheel and sdist builds.
Known risks
- The minimum Python version remains 3.11 pending an owner decision about raising it to 3.12.
- The MCP tool name
deep_scanremains unchanged pending an owner decision; the similarly named CLI command can connect to servers. - Identity collisions in identity and inventory matching.
- Process sightings are deduplicated by name before owner classification.
- Grading evidence is limited to eight findings, and
criticalranks belowlow. - Collector failures can be silent.
--jsonis ignored bysourcesandgrade-missing.- Report writes are not atomic.
- Markdown and Rich output escaping differs.
- Dependency major upgrades, moving off Hatchling, a coverage threshold, package publishing, tags, and releases remain out of scope.
Next steps
Resolve the Python floor and MCP tool naming decisions, then address the listed behavior risks in a follow-up wave.
shadow MCP Fragen
Wie füge ich shadow MCP zu Claude Code hinzu?
Führe claude mcp add shadow-mcp -- uvx shadow-mcp in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich shadow MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Welche Tools bietet shadow MCP?
Er stellt 4 Tools bereit, darunter scan_local, discover_local, deep_scan, list_sources.
Was macht shadow-mcp?
Es entdeckt, inventarisiert und bewertet die Risikostufe von MCP servern auf deinem Rechner, indem es Konfigurationsdateien und laufende Prozesse scannt.
Ist der Discovery-Prozess sicher?
Ja, der Discovery-Prozess ist read-only; die Collector parsen Configs und listen Prozesse auf, ohne die gefundenen Daten zu verändern.
Wie geht das Tool mit Secrets um?
Es erfasst die Namen von Umgebungsvariablen, um potenzielle Secrets zu markieren, speichert aber niemals die tatsächlichen Werte und schwärzt Inline-Credentials.