MCPAudit

mcp-audit

[](https://pypi.org/project/mcp-audits/) [](https://pypi.org/project/mcp-audits/) [](https://github.com/saagpatel/MCPAudit/actions/workflows/ci.yml) [](https://github.com/saagpatel/MCPAudit/actions/workflows/codeql.yml) [](LICENSE)

> ### Audit what your AI agents can actually touch.

Every MCP server wired into your editor is a process that can read your files, reach the network, or run shell commands on your behalf — frequently launched from a remote npx/uvx package that can change underneath you. mcp-audit reads the MCP configs already on your machine and tells you what each server can do, how risky it is, whether its tool descriptions hide adversarial instructions, and whether anything changed since you last looked.

Read-only by default: it never edits a config and reports env-var key names only (never values). Use --skip-connect for a zero-touch config-only pass that does not spawn MCP servers or contact remote endpoints; connected scans, package verification, downloads, and LLM analysis make their extra reach explicit in the command.

> 🌐 Try it in your browser, no install: paste any MCP client config at mcp-audit.saagarpatel.dev for an instant config-only trust report. It runs this exact engine, never launches configured servers, never contacts configured endpoints, and stores nothing. The CLI below adds the connected deep checks (prompt-injection, SSRF, the lethal trifecta, schema drift, SARIF).

⚡ 60-second start

No install required — uv runs it in a throwaway environment. This reads the MCP configs already on your machine, connects to each configured server to read its real tool schemas, and flags SSRF-shaped tools:

uvx --from mcp-audits mcp-audit scan --ssrf-check

It stays read-only the whole time — it never edits a config and reports env-var key names only, never values. Sample output:

╭───────────────────── mcp-audit scan ─────────────────────╮
│ Scanned 5 servers across 2 clients. 1 high-risk.         │
│ 0 failed to connect. (2.4s)                              │
╰──────────────────────────────────────────────────────────╯
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Server     ┃ Client         ┃ Tools ┃ Prompts ┃ Resources ┃ Risk ┃ Non-Tool ┃ Top Permissions            ┃ Status    ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│ github     │ claude_desktop │    26 │       0 │         0 │  9.4 │ n/a      │ file_write, network, exfil │ connected │
│ filesystem │ claude_desktop │    12 │       0 │         0 │  6.8 │ n/a      │ file_write, file_read      │ connected │
│ memory     │ cursor         │     9 │       0 │         0 │  5.3 │ n/a      │ file_write                 │ connected │
│ fetch      │ cursor         │     1 │       0 │         0 │  3.5 │ n/a      │ network                    │ connected │
│ time       │ claude_desktop │     2 │       0 │         0 │  1.5 │ n/a      │ none                       │ connected │
└────────────┴────────────────┴───────┴─────────┴───────────┴──────┴──────────┴────────────────────────────┴───────────┘

──────────────────────────────── SSRF Warnings ────────────────────────────────
┏━━━━━━━━┳━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ Server ┃ Type ┃ Target  ┃ Severity ┃ Pattern         ┃ Evidence          ┃ Suggested Action     ┃
┡━━━━━━━━╇━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ fetch  │ tool │ fetch   │ medium   │ url param +     │ url: string       │ Restrict to a host   │
│        │      │         │          │ fetch verb      │ (caller-supplied) │ allowlist; never     │
│        │      │         │          │ (MCP011)        │                   │ proxy caller URLs    │
└────────┴──────┴─────────┴──────────┴─────────────────┴───────────────────┴──────────────────────┘

> Sample output with illustrative public server names. Higher risk = a broader surface to sandbox, not "malicious." Want a zero-touch pass first? Add --skip-connect to reason purely from your config — no servers spawned, no network calls. Stack --trifecta-check or --shadow-check alongside --ssrf-check to hunt more attack surfaces, and --json / --sarif / --html to pipe results into CI or a dashboard.

Connected public-fixture demo (fetch, sequential-thinking, time; no auth tokens or workstation configs):

Zero-touch preview against the bundled public fixture:

Install it permanently once you're hooked:

uv tool install mcp-audits                # adds the `mcp-audit` command to your PATH
mcp-audit scan                            # connected scan of every configured client

Drop it into CI in one step — the composite GitHub Action runs the scan and writes SARIF straight to GitHub code scanning:

- uses: saagpatel/MCPAudit@v2.4.0        # config-only by default; optional policy gate exits 2

SARIF proof from the public fixture scan:

Policy gate demo from the same zero-touch public fixture:

Self-contained HTML report preview from a redacted config-only scan:

Teach the risk safely: [examples/sandbox/](examples/sandbox/) is a public-safe MCP prompt-injection sandbox with synthetic configs, benign twins, malicious-lookalike tool descriptions, a static config-only MCPAudit report, and a connected-tool manifest that demonstrates what config-only mode can and cannot prove.

PyPI package: mcp-audits · installed command: mcp-audit · full flag and detector reference below.

---

Use as an MCP server

mcp-audit is also an MCP server. Point any MCP client (Claude Code, Claude Desktop, Cursor) at it and your agent can audit its own MCP attack surface on demand: enumerate every configured server, risk-score them, and pull injection, SSRF, lethal-trifecta, shadowing, and drift findings without leaving the conversation.

uvx --from mcp-audits mcp-audit serve

Add it to a client config (Claude Code shown):

{
  "mcpServers": {
    "mcp-audit": {
      "command": "uvx",
      "args": ["--from", "mcp-audits", "mcp-audit", "serve"]
    }
  }
}

stdio only, by design. This server reads the MCP configs already on your machine, so it runs locally over stdio and is never offered as a hosted remote. It stays read-only (it never edits a config) and reports env-var key names only, never values.

All tools are read-only and take no URL or filesystem path; server discovery is automatic from the standard client config locations.

| Tool | Purpose | Args | |---|---|---| | scan_mcp_servers | Full audit of every discovered MCP server; returns the JSON report | skip_connect: bool = false | | check_server | Audit a single server by name | name: str | | get_high_risk_servers | Servers with a composite risk score of 7.0 or higher | none | | list_discovered_servers | Names and clients of all discovered servers (config-only, no spawning) | none | | get_injection_findings | Prompt-injection findings across all servers | none | | get_ssrf_findings | SSRF-shaped tools and resources across all servers | none | | get_trifecta_findings | Lethal-trifecta findings (per-server and fleet-level) | none | | get_shadowing_findings | Cross-server tool-name shadowing collisions | none | | get_escalation_findings | Capability-escalation ("rug pull") deltas vs the pin baseline | none | | get_provenance_findings | Launch-config and provenance drift vs the pin baseline | none | | get_integrity_findings | Launch-artifact on-disk hash drift vs the pin baseline | none | | get_package_verify_findings | Registry package-hash verification vs the pin baseline | none | | get_artifact_verify_findings | Byte-level artifact verification vs the pin baseline | none |

The five drift tools (get_escalation_findings, get_provenance_findings, get_integrity_findings, get_package_verify_findings, get_artifact_verify_findings) compare against a saved baseline, so run mcp-audit pin first.

Every get_*_findings tool returns a JSON object with findings and warnings lists. warnings names any requested check that was skipped or degraded (for example, a drift tool called with no pin baseline) — so an empty findings list with empty warnings genuinely means "checked, clean".

---

Features

• Capability inventory — catalogs server tools, prompts, and resources; tool, prompt, and resource capabilities are classified across six permission categories: file_read, file_write, network, shell_execution, destructive, exfiltration
• Config-only inference — scan --skip-connect infers conservative risks from declared commands, transports, credential key names, package runners, and remote URLs
• Config health diagnostics — discover and scan flag duplicate server names, conflicting command or URL definitions, missing stdio commands, missing local command paths, project/global scope conflicts, package-runner launches, deprecated SSE transports, shell-wrapper launches, remote endpoints, and credential-heavy configs before users pin or connect; JSON reports include additive config_health_findings
• Risk scoring — composite 0–10 per server as a weighted sum of tool permission categories, with a five-dimension breakdown (file access, network, shell, destructive, exfiltration); prompt/resource findings also produce an additive non_tool_risk signal without changing risk_score.composite
• Stable finding metadata — permission and prompt-injection findings include stable rule IDs, severity, evidence, and suggested remediation so reports are easier to triage
• Local policy gates — scan --policy policy.yaml evaluates reports against local YAML rules and exits nonzero for CI enforcement
• Report redaction — terminal, JSON, SARIF, and HTML report paths share a redaction layer for likely credential values; scan --redact adds an opt-in field-report pass that also scrubs the machine hostname and home-path usernames (/Users/, /home/, C:\Users\) from --json/--sarif/--html output, and replaces server names with stable aliases (server-01, …) everywhere they appear — structured fields, free-text summaries, and command basenames — so a config-only report is safe to share (the field-report checklist stays the backstop for any residual free-text specifics)
• Prompt injection detection — scan --inject-check scans tool, prompt, and resource text for instruction-override patterns, hidden directives, fake role turns, and adversarial phrasing; pattern-based, no LLM required
• SSRF detection — scan --ssrf-check flags tools and resources whose interface lets a caller steer a server-side request target (URL/host params paired with fetch verbs, caller-templated remote resource hosts); static and schema-derived, never issues a request or reads a credential value
• Egress detection — scan --egress-check audits where a server may send data: destinations outside --egress-allowlist (MCP040, MED), unbounded caller-controlled targets (MCP041, HIGH), and the trusted-destination residual for allowlisted-but-multi-tenant or credential-bearing hosts (MCP042, LOW/MED — the Cowork lesson). Static and schema/URI-derived; gated via fail_on.egress. See docs/EGRESS-DETECTION.md
• Lethal trifecta detection — scan --trifecta-check detects the canonical agent-exfiltration attack surface: per-server (HIGH, MCP013) when a single server covers all three legs (file_read + untrusted-content ingestion + exfiltration), and fleet-level advisory (MEDIUM, MCP014) when the trifecta assembles only across servers; re-uses inferred permissions, never issues requests or reads credentials
• Tool-name shadowing detection — scan --shadow-check flags cross-server tool-name collisions that could trick an AI agent into routing a call to the wrong server: exact matches (HIGH, MCP015), case/separator-normalised collisions (MEDIUM, MCP016), and homoglyph spoofing via non-ASCII confusable codepoints (HIGH, MCP017); offline, deterministic, no new dependencies
• Schema drift tracking — mcp-audit pin connects to servers and snapshots current tool schemas; subsequent scan --pin-check flags added, removed, and changed tools with plain-language summaries, changed-field hints, suggested actions, and a dry-run refresh workflow for reviewed upgrades. pin --refresh additionally surfaces capability-escalation (MCP018/MCP019) and launch-config/provenance (MCP020–MCP023) deltas in the same preview — unconditionally, so a rug-pull or launch swap can't slip through a baseline refresh
• Capability-escalation ("rug pull") detection — scan --escalation-check compares each tool against its pin baseline and flags security-significant escalations over time: a tool that gained a dangerous capability (MCP018 — HIGH for exfiltration/shell/destructive, MEDIUM for file_write/network) or whose description gained prompt-injection patterns (MCP019, HIGH); pure delta vs the approved baseline, so findings stay scoped to reviewed baseline deltas. See docs/ESCALATION-DETECTION.md
• Provenance / launch-config drift detection — scan --provenance-check compares a server's launch configuration against its pin baseline to catch supply-chain changes the schema check can't see: command/transport swap (MCP020, HIGH), argument/version drift with dangerous-flag escalation (MCP021, MED/HIGH), HTTP endpoint change (MCP022, HIGH), and credential key-name set changes (MCP023, MEDIUM — key names only, never values). See docs/PROVENANCE-DETECTION.md
• Launch-artifact integrity detection — scan --integrity-check hashes the on-disk artifact a server launches (the resolved command binary + local script args) and flags drift vs the pin baseline (MCP024 — HIGH when the SHA-256 changed, MEDIUM when the file is gone). The command string can stay byte-identical while the file it runs is swapped underneath you; this catches that. Offline and deterministic — only local bytes are hashed, nothing is fetched. Package-runner (npx/uvx) launches hash the runner, not the remote package (see registry verification below). See docs/INTEGRITY-DETECTION.md
• Registry package verification — scan --verify-artifacts (opt-in, network) covers the package-runner case the on-disk check can't: it compares the registry-published hash (npm dist.integrity, PyPI sha256) for the exact pinned package@version against the hash captured at pin time (MCP025 — HIGH on a changed published hash, a republish/tampering signal; MEDIUM when unverifiable). Network is contacted only under --verify-artifacts, on both pin (to capture) and scan (to compare). Covers npm + PyPI. See docs/PACKAGE-VERIFICATION.md
• Byte-level artifact verification — scan --download-artifacts (opt-in, network) goes one level deeper than the published-hash compare: it downloads the actual bytes the registry serves, hashes them, and checks them against both the registry's own published hash and a byte-hash captured at pin time (MCP026). It catches a CDN/mirror/MITM serving bytes inconsistent with the registry's integrity metadata (PUBLISHED_MISMATCH, HIGH) and a pinned file whose bytes changed or vanished (BASELINE_MISMATCH, HIGH); a newly-added file on a frozen version is an advisory MEDIUM, not a false alarm. Downloads stream through bounded hashers, never to disk, only to an allowlist of registry/CDN hosts (re-validated on every redirect hop). Network is contacted only under --download-artifacts, on both pin and scan.
• Multi-client support — reads configs from Claude Desktop, Claude Code, Cursor, VSCode, and Windsurf — plus custom paths via `--con

…

Source & license

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

• Author: saagpatel
• Source: saagpatel/MCPAudit
• License: MIT
• Homepage: https://pypi.org/project/mcp-audits/

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