MCP Security Auditor

When you configure a Model Context Protocol (MCP) server in tools like Claude Desktop, Cursor, or an autonomous AI agent, you give an LLM direct access to local tools and system resources. Because these processes run under your user account, an insecure server schema combined with prompt injection can easily lead to remote command execution, credential theft, or unauthorized file modification.

MCP Security Auditor is a static and dynamic analysis tool that checks MCP servers for these security risks before you deploy or connect them. It performs protocol handshakes, evaluates JSON schemas and URI registrations, and flags vulnerabilities in Console, JSON, or SARIF v2.1.0 format for your CI/CD pipeline.

What It Checks

Installation

Using pip

git clone https://github.com/gvbytes/mcp-security-auditor.git
cd mcp-security-auditor
pip install .

For Development

pip install -e ".[dev]"

Usage Examples

1. Audit a Single Server Running Over stdio

Point the auditor to the start command of your MCP server:

mcp-security-auditor --stdio "python path/to/server.py"

2. Audit All Local Claude Desktop Servers in One Command

If you use Claude Desktop, the --claude flag automatically finds your configuration file and audits all registered MCP servers:

mcp-security-auditor --claude

3. Audit Servers from a Custom Config File

You can also point the auditor directly to any Claude Desktop or Cursor configuration file:

mcp-security-auditor --config ~/.config/Claude/claude_desktop_config.json

4. CI/CD Gating with Exit Codes

By default, the auditor exits with code 1 if any HIGH or CRITICAL vulnerability is detected, and 0 otherwise. You can adjust this threshold for your automated builds:

# Fail only on CRITICAL findings
mcp-security-auditor --stdio "node dist/index.js" --fail-on critical

# Informational run (always exits with code 0)
mcp-security-auditor --stdio "node dist/index.js" --fail-on none

5. Suppressing Rules and Excluding Tools

If you have an intentional administrative tool or want to ignore specific rules, pass them on the command line:

mcp-security-auditor --stdio "python server.py" \
  --ignore-rules MCP-T003,MCP-P001 \
  --exclude-tools legitimate_exec_tool

You can also create a .mcpauditor.json file in your repository root to persist these settings:

{
  "fail_on": "high",
  "ignore_rules": ["MCP-T003"],
  "exclude_tools": ["admin_shell"]
}

Export Formats

JSON

mcp-security-auditor --stdio "python server.py" --format json -o report.json

SARIF (GitHub Code Scanning)

Generate SARIF v2.1.0 output to upload findings directly into GitHub's Security tab:

mcp-security-auditor --stdio "python server.py" --format sarif -o results.sarif

GitHub Actions Workflow Example

name: Security Scan MCP Servers

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: |
          pip install mcp-security-auditor
          pip install -r requirements.txt

      - name: Run MCP Security Auditor
        run: |
          mcp-security-auditor \
            --stdio "python server.py" \
            --format sarif \
            --output results.sarif \
            --fail-on high

      - name: Upload SARIF to GitHub Security Tab
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

How It Works Under the Hood

1. Protocol Handshake: Spawns the MCP server child process safely without shell expansion (shlex.split), completes the initialize handshake, and issues the notifications/initialized notification per the MCP spec.
2. Schema and Resource Inspection: Queries tools/list, resources/list, resources/templates/list, and prompts/list, automatically handling pagination cursors.
3. AST & Constraint Analysis: Analyzes input schemas against known attack vectors. Unlike naive keyword matching, it checks whether parameters are constrained by strict JSON Schema enum arrays or regex pattern rules before flagging an issue.
4. Structured Output: Aggregates findings with Common Weakness Enumeration (CWE) mappings, plain-text remediation advice, and reproducible metadata.

Running Tests

To run the automated test suite locally:

pytest -v

How this was built

Most of the code in this project was generated with an AI coding agent (Google Antigravity). I chose the rule set, reviewed the output and tested it against MCP servers.

Note on history: The commit timestamps in this repository were set by hand when the project was uploaded, so they don't show when each change was actually made. The repository was first published on GitHub on 25 June 2026.

License

This project is licensed under the MIT License.