MCPAudit

# mcp-audit

<!-- mcp-name: io.github.saagpatel/mcp-audit -->

[![PyPI](https://img.shields.io/pypi/v/mcp-audits?style=flat-square&logo=pypi&logoColor=white&label=PyPI)](https://pypi.org/project/mcp-audits/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-audits?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/mcp-audits/)
[![CI](https://img.shields.io/github/actions/workflow/status/saagpatel/MCPAudit/ci.yml?style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/saagpatel/MCPAudit/actions/workflows/ci.yml)
[![CodeQL](https://img.shields.io/github/actions/workflow/status/saagpatel/MCPAudit/codeql.yml?style=flat-square&logo=github&label=CodeQL)](https://github.com/saagpatel/MCPAudit/actions/workflows/codeql.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](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.

For pre-run behavioral evidence, MCPAudit also includes
[Proof Before Action](docs/PROOF-BEFORE-ACTION.md): a local-only CLI that runs a
synthetic command in a disposable no-network container, compares observed
effects with a declaration, joins repository MCP dependencies to local
mcp-trust evidence, and exports verifiable JSON plus offline HTML.

For MCP `2026-07-28` cache behavior, the experimental
[Cache Contract Auditor](docs/CACHE-CONTRACT-AUDITOR.md) runs a bounded
logical-clock simulator over program-owned JSON traces. It checks required
`ttlMs`/`cacheScope`, private authorization partitions, exact request keys,
expiry/refresh and validated change-event behavior, linked page scope, and
deterministic tools ordering without running a client, server, or proxy.

> **🌐 Try it in your browser, no install:** paste any MCP client config at **[mcp-audit.saagarpatel.dev](https://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`](https://docs.astral.sh/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:

```bash
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:

```text
╭───────────────────── 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):

![mcp-audit connected SSRF scan demo](docs/assets/hero-scan.gif)

Zero-touch preview against the bundled public fixture:

![mcp-audit config-only scan preview](docs/assets/mcp-audit-config-only-scan.png)

Install it permanently once you're hooked:

```bash
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:

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

SARIF proof from the public fixture scan:

![mcp-audit SARIF findings in GitHub code scanning](docs/assets/ci-sarif.png)

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

![mcp-audit policy gate exits 2](docs/assets/policy-gate.gif)

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

![mcp-audit self-contained HTML report](docs/assets/html-report.png)

**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`](https://pypi.org/project/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.

```bash
uvx --from mcp-audits mcp-audit serve
```

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

```json
{
  "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