Inventories and risk-grades local MCP servers by discovering them across various configuration files and live processes.
Also known as saagpatel/shadow-mcp
- Stars
- 0
- Tools
- 4
- Downloads, 30 days
- 100
- Latest version
- 0.2.0
- Last commit
- Nov 14, 2026
- License
- —
What is shadow MCP?
shadow inventories and risk-grades local MCP servers by discovering them across various configuration files and live processes. It exposes 4 tools, such as scan_local, discover_local, deep_scan.
Summary generated from the project's README
About shadow MCP server
Security researchers and developers can use shadow-mcp to identify and evaluate the security posture of MCP servers running on a local machine. It solves the problem of shadow MCP servers by finding configurations scattered across Claude Code, Claude Desktop, Codex, project-specific .mcp.json files, and live processes that do not bind to a port. This tool provides a complete inventory by merging sightings from different sources into a single logical view of your local environment.
After discovery, the system assigns risk grades by delegating to specialized engines like MCPAudit for capability and injection findings, and mcp-trust for danger grades. Users can perform a static scan based on configuration files or opt into a connected deep-scan that actually spawns stdio servers to enumerate real tools. Results are delivered through terminal tables, machine-readable JSON, or markdown reports, highlighting discrepancies between configured and running servers.
What you can do with it
- 1Audit local server configurationsIdentify all MCP servers hidden in various configuration files and active processes on your machine.
- 2Evaluate real tool capabilitiesPerform a deep scan that connects to servers to see their actual functional permissions.
- 3Generate machine-readable security inventoriesExport a full inventory of your local MCP surface as a JSON file for automated processing.
- 4Monitor shadow server presenceDetect servers that are currently running but are not documented in your standard configuration files.
Written from the project's README. Every use case is checked against a quote from it.
How to install shadow MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall shadow MCP in Claude Code
$ claude mcp add shadow-mcp -- uvx shadow-mcpInstall shadow MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}Install shadow MCP in VS Code
.vscode/mcp.json
{
"servers": {
"shadow-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}Install shadow MCP in VS Code CLI
$ code --add-mcp '{"name":"shadow-mcp","type":"stdio","command":"uvx","args":["shadow-mcp"]}'Install shadow MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}Install shadow MCP in Codex
$ codex mcp add shadow-mcp -- uvx shadow-mcpInstall shadow MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.shadow-mcp] command = "uvx" args = ["shadow-mcp"]
Install shadow MCP in Gemini CLI
$ gemini mcp add -s user shadow-mcp uvx -- shadow-mcpInstall shadow MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"shadow-mcp": {
"command": "uvx",
"args": [
"shadow-mcp"
]
}
}
}shadow MCP tools 4
Detected from the READMEscan_localdiscover_localdeep_scanlist_sources
| scan_local | — | |
| discover_local | — | |
| deep_scan | — | |
| list_sources | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablesaagpatel/shadow-mcp is public and reachablegithub.com/saagpatel/shadow-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Sigstore attestation for shadow-mcppypi.org/project/shadow-mcp/ ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-08github.com/saagpatel/shadow-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from shadow-mcpPass
- No critical advisory in the package or its dependencies43 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubshadow-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 questions
How do I add shadow MCP to Claude Code?
Run claude mcp add shadow-mcp -- uvx shadow-mcp in your terminal. Add --scope user to make it available in every project.
How do I add shadow MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does shadow MCP provide?
It exposes 4 tools, including scan_local, discover_local, deep_scan, list_sources.
What does shadow-mcp do?
It discovers, inventories, and risk-grades MCP servers present on your machine by scanning configuration files and live processes.
Is the discovery process safe?
Yes, discovery is read-only; collectors parse configs and list processes without mutating anything found.
How does it handle secrets?
It records environment variable names to flag potential secrets but never records the actual values, and it redacts inline credentials.