mcp-audit

mcp-audit

[PyPI] [Python] [CI] [CodeQL] [License: MIT]

See what your AI tools' MCP servers can reach.

MCPAudit reviews MCP server configuration and, when asked, lists the tools a server exposes. It highlights declared capabilities, instruction-shaped text heuristics, and changes from a saved pin so you can decide what to investigate. Findings are review signals: a high score means broader capability exposure, not that a server is malicious or unsafe.

[!IMPORTANT] The package is mcp-audits; the command is mcp-audit. The default check is static. check --connect and --connect-all can start configured local programs or contact configured endpoints. Legacy scan never connects: it refuses connecting forms with exit 2 before discovery. Package verification, downloads, and LLM analysis are separate opt-in operations. MCPAudit does not edit configs, and reports environment variable key names, never their values. Review generated reports before sharing them.

Try it

mcp-audit                              # static review of supported configsmcp-audit check --config ./mcp.json    # review this file only; no connectionsmcp-audit demo                         # see a bundled synthetic examplemcp-audit explain MCP007               # explain a finding offline; no config reads

Install with uv:

uv tool install mcp-audits

Or run without installing:

uvx --from mcp-audits mcp-audit demo

What to do with a finding

Start with the suggested action and inspect the named capability or evidence. For example, if a filesystem server can write broadly, restrict its configured directory and review the report again. Pattern-based instruction checks can miss reworded or obfuscated text and can also need human review. A clean report is not a safety certificate.

Review the server's configured access, narrow it if needed, then run the check again.

Use Start here for a guided walkthrough and Reading results to interpret scores, findings, and coverage. How it works explains the check boundary.

Each rule's meaning, possible consequences, manual fix and confidence limits are in the finding reference; mcp-audit explain MCP013 prints the same entry offline. Explicit --config sources are labeled "explicit file; parsed as Claude-style config"; the parser identity does not establish which client uses that file.

Static tool metadata checks also flag malformed MCP header annotations, credential parameters mapped to headers, external schema references and unexpected icon sources. These checks inspect served metadata without fetching schemas or icons.

Use in CI

MCPAudit can write SARIF and evaluate local policy files. Begin with config-only CI, then enable connected checks only where the workflow should start those servers. See the CI guide and policy examples.

For a pinned release example, the composite Action can upload SARIF to GitHub code scanning:

- uses: saagpatel/[email protected]

The release checklist calls out Action references so maintainers can update examples when a new public release is available. Review the action's permissions and inputs before enabling it in a repository.

Choose a review path

The server ID is CLIENT:SCOPE:NAME; use the exact identity from inspect to avoid ambiguous selections. Connected checks can start configured local commands or contact their endpoints.

checkup writes a local, counts-only share card with no names by default; see the checkup guide.

Keep the evidence in context

Configuration-based findings describe declared access. A connected listing adds the tool metadata the server provides, but does not prove what the server will do later. Connected HTTP scans also send one credential-free server/discover request and, on 401, review bounded public authorization metadata. The probe never uses configuration header values and does not run with --skip-connect or for project sources without connection opt-in. These observations do not prove a completed OAuth flow. The optional canary is bounded and exercises only eligible tools under its documented limits. See How it works for the boundary between those observations.

Reports can contain configuration shape, tool names, and evidence text. Secret redaction is best-effort (known issues); review a report before sharing it. Configs are parsed in full, but environment variable values are discarded during parsing and never reported; reports keep key names for context. The output contract lists stable fields and the limits of these outputs.

Status

Stack

MCPAudit uses Python 3.11+, uv, pytest, Ruff, and mypy. JSON, SARIF, and HTML reports are versioned public surfaces. Run make check before proposing changes.

Known risks

Static findings describe configured access and served metadata; they do not prove how a server behaves later. Secret redaction is best-effort. Upgrading from 2.x? Read the 3.0 migration guide; the 3.0 boundary proposal records the decisions behind it.

Next steps

Use explicit synthetic fixtures for local changes, preserve read-only defaults, and keep coverage claims tied to completed checks. Re-enable Python 3.15 after an rpds-py/PyO3 lock refresh.

More documentation

Explore pinning, shadow review, suppressing findings, the trust packet guide, MCP trust packet, output contract, and sandbox fixtures. See the documentation index, labs, maintainer procedures in maintainers/, and older material in archive/.