The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Shadow MCP listing page.
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.
~/.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.personal-ops vs
personal_ops), tracking every provenance.The risk model and its OWASP mapping live in docs/risk-model.md.
shadow-mcp grades against your local checkouts of MCPAudit (../MCPAudit) and
mcp-trust (../mcp-trust/registry.db). Override with SHADOW_MCP_MCPTRUST_DB
or --registry-db.
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).
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.
The grading engines are an optional engines dependency-group, resolved to your
local checkouts of ../MCPAudit and ../mcp-trust via [tool.uv.sources]. The
tool degrades to discovery-only without them (engine-backed tests skip cleanly),
so CI installs without them:
--connect/deep-scan is the one path that
executes servers, and only when you explicitly ask.)*.inventory.json as private (it is
git-ignored by default).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.
| 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 only the named servers (static, no spawning). Accepts names: list[str]. Returns JSON. |
list_sources | Per-collector source counts from a discover run. Returns JSON. |
LOCAL only. The MCP server never connects to hosted MCP endpoints — all
grading is static (config-based). connect=False is enforced unconditionally;
no server is ever spawned from an MCP tool call.
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.