mcp-security

Security scanner for MCP (Model Context Protocol) servers. Think of it as npm audit for AI agents.

Installation

npm install -g mcp-security

Or run directly:

npx mcp-security

Usage

Basic Scan

# Auto-detect and scan MCP configs
mcp-security scan

# Scan specific config
mcp-security scan ./path/to/mcp.json
mcp-security scan ~/.cursor/mcp.json

Output Formats

# Terminal output (default)
mcp-security scan

# JSON output (for scripting)
mcp-security scan --json

# SARIF output (for GitHub Actions)
mcp-security scan --sarif > results.sarif

CI/CD Integration

# .github/workflows/security.yml
name: MCP Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run MCP Security Scan
        run: npx mcp-security scan --sarif > results.sarif
        
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif

Detection Rules

Prompt Injection (PI001-PI003)

Detects attempts to manipulate LLM behavior through tool descriptions:

• "ignore previous instructions"
• "override all instructions"
• Base64 encoded payloads
• Hidden commands in code blocks
• Unusually long descriptions

Tool Shadowing (TS001-TS002)

Identifies dangerous tool names that could shadow built-ins:

• read_file, write_file, execute
• shell, bash, eval
• Name conflicts between servers

Config Exposure (CE001-CE004)

Finds exposed secrets in configuration:

• OpenAI, Anthropic, AWS API keys
• GitHub tokens
• Hardcoded passwords in args or env

Excessive Permissions (EP001-EP005)

Detects overly permissive configurations:

• Root filesystem access ("/")
• sudo in commands
• Unrestricted network bindings

Exit Codes

| Code | Meaning | |------|---------| | 0 | No issues (or only low severity) | | 1 | High or medium severity findings | | 2 | Scanner error |

Config Locations

Auto-detected config files:

| Application | Path | |------------|------| | Cursor | ~/.cursor/mcp.json, ./.cursor/mcp.json | | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop (Linux) | ~/.config/claude/claude_desktop_config.json | | VS Code | ~/.vscode/mcp.json, ./.vscode/mcp.json | | Generic | ./mcp.json, ./.mcp/config.json |

Example Output

🔍 MCP Security Scanner v0.1.0
   2026-02-18T12:00:00.000Z

Scanning: ~/.cursor/mcp.json
Servers:  2

   ✓ filesystem (3 tools) — No issues
   ⚠ custom-tools (2 tools) — 1 findings

Findings:

🔴 HIGH: Potential prompt injection in tool description
   Server: custom-tools
   Tool: process_data
   Pattern: Attempts to override previous instructions
   Found: "ignore all previous instructions"
   → Review and remove suspicious instructions from tool description

Summary:
   1 high · 0 medium · 0 low

License

MIT

Contributing

Issues and PRs welcome at GitHub.