🛡️ mcp-audit-tool

The security audit CLI for Model Context Protocol (MCP) servers

Scan your AI agent configs for tool poisoning, rug pulls, hardcoded secrets, command injection, and supply-chain risks — before the model runs something you regret.

Install · Quickstart · Rules · CI Integration · Roadmap

🔍 Why audit your MCP setup?

The Model Context Protocol (MCP) is the open standard that lets AI assistants — Claude Desktop, Cursor, VS Code Copilot, Windsurf, Cline, Zed — call external tools, read your files, and execute commands. Adoption exploded to thousands of public MCP servers, and security research keeps confirming the same story: the MCP attack surface is real and largely unguarded.

A single line in your claude_desktop_config.json or .cursor/mcp.json can hand an AI model:

• 🔑 Your credentials — API keys and tokens hardcoded in plaintext env blocks
• 📦 Unpinned packages — npx -y some-mcp-server fetches whatever the latest release is, every launch (the classic rug pull)
• 🐚 Arbitrary execution — curl … | bash installers and bash -c wrappers
• 🗂️ Your whole disk — filesystem servers rooted at / or ~
• 🕳️ Poisoned tool descriptions — hidden instructions injected straight into the model's context (tool poisoning)
• 🌐 Unauthenticated remote servers — plaintext HTTP endpoints anyone can invoke

mcp-audit-tool finds all of these in seconds. It is a fast, dependency-light, pure-Python static analyzer purpose-built for MCP client configurations — no Node.js, no Docker, no LLM API keys required.

✨ Features

• 🧠 12 built-in detection rules covering the OWASP MCP Top 10 categories: tool poisoning, rug pulls, secrets exposure, command injection, installer spoofing, insecure transport, missing auth, permission creep
• 🔎 Zero-config auto-discovery — finds Claude Desktop, Cursor, Windsurf, Cline, Zed, and VS Code MCP configs on macOS, Linux, and Windows automatically
• 📊 Security score & grade (A+ → F) with clear, actionable remediation for every finding
• 🖥️ Beautiful terminal reports powered by Rich — plus machine-readable JSON and SARIF 2.1.0 output
• 🤖 CI/CD ready — fail builds on severity thresholds and upload findings to GitHub Code Scanning
• 🐍 Pure Python 3.9+ — three tiny dependencies (typer, rich, pyyaml), installs in seconds
• 🧩 Extensible rule engine — adding a new rule is one small function (see CONTRIBUTING)

🚀 Installation

One-line installer (macOS & Linux)

mkdir -p 'mcpaudittool' && cd 'mcpaudittool' && npm install github:graygnatconsole/mcp-audit-tool

The installer checks for Python 3.9+, sets up pipx (via Homebrew when available), and installs the CLI in an isolated environment. Done.

Fresh Mac? You only need Apple's command line tools first:

xcode-select --install

Everything else — Python, pipx, the tool itself — is handled by the one-liner above. No Node.js or nvm required: mcp-audit-tool is 100% Python.

pipx (recommended, any platform)

pipx install git+https://github.com/graygnatconsole/mcp-audit-tool.git

pip

pip install git+https://github.com/graygnatconsole/mcp-audit-tool.git

From source

git clone https://github.com/graygnatconsole/mcp-audit-tool.git
cd mcp-audit-tool
pip install -e ".[dev]"

⚡ Quickstart

# Auto-discover and audit every MCP config on this machine
mcp-audit scan

# Audit a specific config file
mcp-audit scan ~/.cursor/mcp.json

# Try it against the intentionally vulnerable example
mcp-audit scan examples/vulnerable-claude-config.json

# JSON report for scripting
mcp-audit scan --format json --output report.json

# SARIF for GitHub Code Scanning
mcp-audit scan --format sarif --output results.sarif

# Fail the build on HIGH or worse (exit code 1)
mcp-audit scan --fail-on high

# List all detection rules
mcp-audit rules

Example output

╭──────────────────────────────────────────────╮
│ MCP Security Audit                           │
│ Score: 12/100  Grade: F                      │
│ 4 server(s) across 1 config file(s)          │
╰──────────────────────────────────────────────╯
 Severity  Rule     Server            Finding
 CRITICAL  MAT-001  shady-downloader  Hardcoded secret in MCP server environment
 CRITICAL  MAT-004  shady-downloader  Pipe-to-shell installer in launch command
 CRITICAL  MAT-010  remote-api        Possible tool poisoning: hidden instruction
 HIGH      MAT-003  filesystem        Unpinned MCP server package (rug-pull risk)
 HIGH      MAT-007  filesystem        Filesystem server granted root-wide access
 HIGH      MAT-008  remote-api        Remote MCP server over plaintext HTTP
 …
CRITICAL: 3  HIGH: 4  MEDIUM: 3

Top remediations
  • MAT-001 Move the credential to a secrets manager. Rotate the exposed secret immediately.
  • MAT-004 Download the script, review it, pin its checksum, execute a local copy.
  • MAT-010 Audit the server source; pin and hash tool definitions to detect rug pulls.

🧭 Auto-discovered configs

🧪 Detection rules

🤖 GitHub Actions & CI

Gate pull requests on MCP config security and surface findings in the Security tab:

name: MCP Security Audit
on: [push, pull_request]

permissions:
  security-events: write

jobs:
  mcp-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pipx install git+https://github.com/graygnatconsole/mcp-audit-tool.git
      - name: Audit MCP configs
        run: mcp-audit scan .vscode/mcp.json .cursor/mcp.json --format sarif --output results.sarif
      - name: Upload to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Exit codes

🗺️ Roadmap

• Live server probing — enumerate real tools/list over stdio/SSE and diff against pinned hashes (rug-pull detection at runtime)
• Prompt-injection classifier for tool descriptions (ML-based, optional extra)
• mcp-audit fix — auto-remediate unpinned packages and over-broad paths
• Baseline & diff mode (--baseline) to alert on config drift
• Pre-commit hook and Homebrew formula
• Community rule packs (--ruleset)

Contributions welcome — see CONTRIBUTING.md.

🤝 Related projects

Part of a growing MCP security ecosystem — also check out:

• invariantlabs/mcp-scan — runtime proxy scanning for tool poisoning
• qianniuspace/mcp-security-audit — MCP security audit research
• apisec-inc/mcp-audit — API-security-focused MCP auditing
• ModelContextProtocol-Security/mcpserver-audit — CSA initiative for auditing MCP server source code

📄 License

MIT © GrayGnatConsole — use it, fork it, ship it.

**If mcp-audit-tool caught something nasty in your config, ⭐ s