Install and run mcp-audit

Install

pip install mcp-audit-scanner

Or with uv: uv tool install mcp-audit-scanner. The package is mcp-audit-scanner; the command is mcp-audit. It needs Python 3.11 or later. Standalone binaries for macOS (Apple silicon), macOS (Intel), Linux (x86-64) and Windows (x86-64) are on GitHub Releases.

Optional extras add features that need more dependencies:

First run, by job

1. Before you install a server

   mcp-audit vet @modelcontextprotocol/server-filesystem

   Copy

   Registry status, recorded advisories, capabilities and lookalike names for a public package. Exits 1 for an advisory with no fix or a lookalike name. Add --format json for the verdict document.

2. Before you open a cloned repo

   mcp-audit scan --project ./cloned-repo --include-agent-files

   Copy

   Walks the repo for MCP configs, agent settings, editor auto-run files and instruction files, and reports what each can do.

3. On your machine

   mcp-audit checkmcp-audit fixmcp-audit fix --apply

   Copy

   check gives a grade and the top findings with a fix for each. fix shows the safe fixes as a diff; --apply writes them and keeps a .bak copy.

4. Lock what you approved

   mcp-audit lockgit add mcp-lock.jsonmcp-audit lock --verify

   Copy

   lock records the approved servers, never secret values. lock --verify exits 1 when anything drifts; lock --accept records a reviewed change.

5. Find servers nobody approved

   mcp-audit shadow --allowlist .mcp-audit-allowlist.yml

   Copy

   Lists every MCP server on the machine as sanctioned or shadow (OWASP MCP09). Add --continuous to emit events when configs change.

6. Cut the blast radius

   mcp-audit killchain

   Copy

   Ranks the few changes that break the most attack paths between your servers.

In CI

GitHub Action

The Action installs mcp-audit, scans the MCP configs and Claude Code settings in the checked-out repository, uploads SARIF to GitHub code scanning, and fails the job at the severity you choose. With lock-verify, it also fails when the repo drifts from mcp-lock.json.

name: mcp-audit
on: [push, pull_request]
jobs:
  mcp-audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: adudley78/mcp-audit@v0.21.1
        with:
          severity-threshold: high
          lock-verify: true

Pin the Action to a release tag. Before 1.0 there is no floating major tag such as @v1.

pre-commit

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/adudley78/mcp-audit
    rev: v0.21.1
    hooks:
      - id: mcp-audit
      - id: mcp-audit-lock-verify

• mcp-audit: Scan MCP server configuration files for security vulnerabilities (runs mcp-audit scan --severity-threshold high).
• mcp-audit-lock-verify: Block a commit that drifts from the reviewed mcp-lock.json (runs mcp-audit lock --verify --if-present).

Pull request comments

mcp-audit diff <base> <head> --format pr-comment summarises what a pull request changes in MCP configs: servers, tools, credentials and endpoints, with a risk level. The Action's mode: diff input posts it for you.

In your editor

The mcp-audit extension on Open VSX (mcp-audit.mcp-audit-vscode) shows findings as you edit an MCP config in VS Code-compatible editors such as Cursor: underlines on the server, hover cards with the fix, and the grade in the status bar. It calls the mcp-audit command, so install the package first.

Output and integrations

• scan --format writes terminal, json, sarif, nucleus. SARIF carries OWASP MCP Top 10 codes into GitHub code scanning.
• dashboard opens a self-contained HTML attack graph; nothing is loaded from a CDN. scan --report pdf writes a PDF report.
• sbom and snapshot write CycloneDX documents; snapshot --stream emits one finding per line for a SIEM.
• push-nucleus sends a scan to Nucleus Security through its FlexConnect API, and merge combines scans from many machines into one fleet report.

Every command 40

Read from the source at build time. Run mcp-audit <command> --help for flags.

Documentation

The full documentation lives in the repository. Start with the README and the changelog.

• docs-usage.md Getting started, all CLI commands and flags, common workflows
• github-action.md GitHub Action setup, example workflows, exit code behaviour
• building-binaries.md How the shipped PyInstaller binary is built (one composite, CI and release); per-release CycloneDX SBOMs
• scoring.md Scan score methodology, grade thresholds, score/filter interaction
• telemetry.md Privacy policy: what mcp-audit does and does not collect
• baselines.md Baseline snapshot workflow, drift detection, commands
• governance.md Governance policy schema, quickstart, worked examples
• writing-rules.md Policy-as-code YAML rule format, match types, contributing
• sast-rules.md Semgrep rule catalog, severity rationale, false positive guidance
• extensions.md IDE extension scanner overview, supported clients, analysis layers
• supply-chain.md Supply chain attestation, hash verification, contribution guide
• dependency-reachability.md Why Dependabot findings in transitives are unused, and which call-site changes invalidate those dismissals
• severity-framework.md CVSS base scores and OWASP Agentic Top 10 mappings for every finding ID; decision tree for calibrating new findings
• registry.md Known-server registry reference, contributing entries
• registry-contributions.md How to submit new registry entries
• research/2026-10-top100-npm/ Scan of the 100 most-downloaded MCP servers on npm (2026-10-22): corpus, aggregate numbers, scripts
• nucleus-integration.md push-nucleus command, FlexConnect API, fleet push examples
• fleet-scanning.md Fleet merge workflow, asset prefix, enterprise deployment
• enterprise-deployment.md Fleet deployment guide for IT/security teams
• pre-commit.md Pre-commit hook setup and configuration
• contributing-rules.md Community detection rule contribution guide (template, bounty, attribution)
• contributing-sast-rules.md Semgrep SAST rule authoring guide
• community-rule-spec.md Community rule YAML format specification (Apache 2.0; ecosystem-adoptable)
• contributors.md Attribution list for accepted community contributors
• manual-test-matrix.md Release-candidate manual validation checklist
• offline-verification-findings.md Empirical test of cosign's *keyless* verification path with zero network access. Not about the advisory feed, which signs with a static key and is offline by construction — see the scope note at the top