How to Audit MCP Server Configurations for Security Risks

What mcp-audit-tool does

mcp-audit-tool is a pure-Python command-line security analyzer for Model Context Protocol (MCP) client configurations. It statically scans configurations used by clients such as Claude Desktop, Cursor, Windsurf, Cline, Zed, and VS Code.

MCP servers can read files, execute commands, access credentials, and provide tools to AI assistants. A single unsafe configuration entry may expose secrets, grant excessive filesystem access, download an untrusted package, or inject instructions into a model's context. The auditor helps identify these risks before an MCP server runs.

The tool does not require Node.js, Docker, or an LLM API key. It supports Python 3.9 and later and produces terminal, JSON, and SARIF 2.1.0 reports.

Key features

• Automatically discovers supported MCP configurations across macOS, Linux, and Windows.
• Checks 12 security rules covering secrets, command execution, permissions, transport, authentication, tool poisoning, and supply-chain risks.
• Calculates a security score and grade from A+ to F.
• Displays actionable remediation guidance for findings.
• Exports machine-readable JSON and SARIF reports.
• Supports severity-based build failures for CI/CD pipelines.
• Uses an extensible rule engine for adding future checks.

Installation and setup

Option 1: macOS and Linux installer

The README provides the following one-line installation command for macOS and Linux:

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

The installer checks for Python 3.9 or newer, sets up pipx through Homebrew when available, and installs the CLI in an isolated environment. On a fresh Mac, install Apple's command-line tools first if necessary:

xcode-select --install

Option 2: pipx

pipx is the recommended installation method for any supported platform:

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

Option 3: pip

You can also install the package directly into a Python environment:

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

Option 4: install from source

Clone the repository and install it in editable mode with development dependencies:

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

Run your first audit

After installation, run the scanner without a path to automatically discover MCP configurations on the machine:

mcp-audit scan

To scan one specific configuration, pass its path as an argument:

mcp-audit scan ~/.cursor/mcp.json

The repository also includes an intentionally vulnerable example that is useful for testing:

mcp-audit scan examples/vulnerable-claude-config.json

A terminal report includes the overall score, grade, number of servers and configuration files, severity counts, affected servers, rule identifiers, and suggested remediations. A poor result may identify hardcoded credentials, unsafe shell commands, unpinned packages, broad filesystem paths, insecure remote endpoints, or suspicious tool descriptions.

Understand automatic configuration discovery

When no file path is supplied, the tool searches common locations for supported MCP clients. Examples include:

• Claude Desktop configuration under the application support directory on macOS, Linux, and Windows.
• ~/.cursor/mcp.json for Cursor.
• ~/.codeium/windsurf/mcp_config.json for Windsurf on macOS.
• Cline settings in the relevant VS Code global storage directory.
• ~/.config/zed/settings.json for Zed on macOS and Linux.
• Project-level files such as .vscode/mcp.json, .cursor/mcp.json, .mcp.json, and mcp.json.

If you want predictable audit scope, pass the exact configuration files instead of relying on discovery.

Review the detection rules

Use the rules command to list the available checks:

mcp-audit rules

The built-in rules include:

• MAT-001: hardcoded OpenAI, Anthropic, GitHub, AWS, Slack, Google, or private-key secrets in server environment variables.
• MAT-002: sensitive host environment variables passed to a server process.
• MAT-003: unpinned npx, uvx, or pipx packages that may create rug-pull and supply-chain risks.
• MAT-004: curl or wget output piped to a shell.
• MAT-005: dangerous commands such as rm -rf, sudo, chmod 777, or eval.
• MAT-006: shell -c wrappers that increase command-injection exposure.
• MAT-007: filesystem servers rooted at /, ~, or $HOME.
• MAT-008: remote MCP servers using plaintext HTTP.
• MAT-009: remote MCP servers without configured authentication.
• MAT-010: hidden-instruction indicators in tool descriptions, which may suggest tool poisoning.
• MAT-011: destructive tools placed on an auto-approve list.
• MAT-012: wildcard * permissions.

Generate JSON and SARIF reports

Use JSON when another script or security process needs to consume the findings:

mcp-audit scan --format json --output report.json

For GitHub Code Scanning and other SARIF-compatible systems, generate a SARIF 2.1.0 file:

mcp-audit scan --format sarif --output results.sarif

These formats are useful when terminal output is not enough, such as scheduled audits, dashboards, pull-request checks, or centralized security reporting.

Fail builds on serious findings

Use --fail-on to make the command return a failing status when findings meet or exceed a severity threshold:

mcp-audit scan --fail-on high

The documented exit codes are:

• 0: the scan completed without findings at or above the selected threshold.
• 1: one or more findings met or exceeded the selected threshold.
• 2: a usage error occurred, such as a missing file, parse error, or invalid option.

Integrate the audit into GitHub Actions

You can audit project-level MCP files during pushes and pull requests, then upload the results to GitHub's 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

The workflow grants security-events: write, scans the selected configuration files, and uploads the generated SARIF file through GitHub's CodeQL action.

Advanced usage and remediation tips

Audit before allowing a server to run

Run an audit whenever you add or update an MCP server configuration. This is especially important for entries using package runners such as npx or uvx, because unpinned packages can change between launches.

Pay attention to critical findings

Critical findings include hardcoded secrets, pipe-to-shell installers, and tool-poisoning indicators. Move exposed credentials to a secrets manager and rotate them immediately. Download installer scripts for review, pin their checksums, and execute reviewed local copies instead of piping remote content directly into a shell.

Reduce permissions

Restrict filesystem servers to the smallest required directory rather than /, ~, or $HOME. Replace wildcard permissions with narrowly scoped permissions and review destructive tools before placing them on an auto-approve list.

Protect remote servers

Prefer secure transport over plaintext HTTP and configure authentication for remote MCP servers. The scanner flags both insecure transport and missing authentication so that remote access is not left exposed by default.

Use the rule engine as a starting point

The project describes its rule engine as extensible: adding a new rule requires one small function. If your organization has additional MCP security requirements, review the repository's contribution guidance before implementing and contributing a rule.

Conclusion

mcp-audit-tool provides a practical first security check for MCP client configurations. Install it with pipx, scan discovered or explicitly selected files, inspect the score and remediation guidance, and export JSON or SARIF when integrating with automation. Adding the scan to CI helps catch unsafe MCP changes before an AI assistant can execute them.