mcp-shield-cli 0.2.1

Security scanner, runtime proxy, and audit logger for MCP servers

MCP Shield

Like Bandit for Python code, but for MCP servers.

Security scanner, runtime proxy, and audit logger for Model Context Protocol servers.

Install

pip install mcp-shield-cli

Requires Python 3.11+ and Node.js (for npx-based MCP servers).

Usage

mcp-shield test — scan a server

# Scan a local stdio server
mcp-shield test "npx -y @modelcontextprotocol/server-filesystem /tmp"

# Scan a remote HTTP server
mcp-shield test "http://localhost:8080/mcp"

# Run only specific suites (compliance, security, advisory, or all)
mcp-shield test "npx server" --suite security
mcp-shield test "npx server" --suite security --suite advisory

# Pass environment variables to the server process
mcp-shield test "npx server" --env API_KEY=sk-123 --env DB_URL=postgres://host/db

# Save JSON report to file
mcp-shield test "npx server" --output report.json

# JSON to stdout (for piping)
mcp-shield test "npx server" --format json

# SARIF output (for GitHub Code Scanning)
mcp-shield test "npx server" --format sarif

# SARIF to file (can combine with any --format)
mcp-shield test "npx server" --sarif-output report.sarif

# Both terminal and JSON output
mcp-shield test "npx server" --format both --output report.json

# CI mode: exit code 1 if any high+ severity check fails
mcp-shield test "npx server" --fail-on high

# Enable ML-based poisoning detection (DeBERTa, slower but more accurate)
mcp-shield test "npx server" --ml

# Set connection/check timeout (default 30s)
mcp-shield test "npx server" --timeout 10

Example output:

 Check        | Result | Severity | Message
 COMP-001     |  PASS  | critical | Handshake OK
 COMP-002     |  PASS  | error    | Server identity: filesystem-server v0.2.0
 SEC-002      |  WARN  | high     | Found 11 potential injection vector(s) (CWE-78, CWE-89, CWE-22)
 SEC-004      |  FAIL  | high     | 2 dangerous tool(s): move_file, edit_file (CWE-78, CWE-250)
 SEC-005      |  WARN  | medium   | Write scope: local filesystem (CWE-434)
 ADV-002      |  WARN  | info     | External dependencies: filesystem access

 Score: 57/100  Grade: D

─────────────── Recommendations ───────────────

  [1] Block dangerous tools (SEC-004) (CWE-78, CWE-250)
      Tools: move_file, edit_file
      Action: Add --deny rules in proxy or require user confirmation

┌──── Ready-to-use proxy command ────┐
│ mcp-shield proxy "npx ..." \       │
│   --deny move_file --deny edit_file│
└────────────────────────────────────┘

mcp-shield proxy — runtime firewall

# Block specific tools by name (glob patterns)
mcp-shield proxy "npx server" --deny "delete_*" --deny "exec_*"

# Allow only safe tools (everything else is blocked)
mcp-shield proxy "npx server" --allow "read_*" --allow "list_*"

# Rate-limit to 30 requests/minute per client
mcp-shield proxy "npx server" --rate-limit 30

# Custom audit database path
mcp-shield proxy "npx server" --audit-db ./my-audit.db

# Require authentication
mcp-shield proxy "npx server" --auth bearer --token admin:secret123
mcp-shield proxy "npx server" --auth bearer --token alice:tok-a --token bob:tok-b

# Combine everything: deny + rate limit + auth + env
mcp-shield proxy "npx server" \
    --deny "git_push" --deny "git_reset" \
    --rate-limit 30 \
    --auth bearer --token ci:token123 \
    --env GITHUB_TOKEN=ghp_xxx

# Proxy a remote HTTP server
mcp-shield proxy "http://upstream:9090/mcp" --deny "drop_*"

The proxy sits between the LLM client and the MCP server:

LLM Client  ──stdio──▶  mcp-shield proxy  ──stdio──▶  MCP Server
                           │
                     ┌─────┴─────┐
                     │ deny list │
                     │ rate limit│
                     │ auth check│
                     │ audit log │
                     └───────────┘

Blocked calls return an error to the client and are logged with the block reason.

mcp-shield audit — query logs

# Show last 50 events (default)
mcp-shield audit show

# Show last 100 events
mcp-shield audit show --last 100

# Filter by tool name
mcp-shield audit show --tool delete_file

# Show only blocked calls
mcp-shield audit show --blocked

# Filter by risk tier (read, write_reversible, write_external, write_sensitive)
mcp-shield audit show --risk write_sensitive

# Filter by client ID (when using --auth)
mcp-shield audit show --client admin

# Combine filters
mcp-shield audit show --blocked --risk write_sensitive --last 20

# Summary statistics (default: last 24 hours)
mcp-shield audit stats

# Stats for a time range (h=hours, d=days, w=weeks, m=months)
mcp-shield audit stats --since 1h
mcp-shield audit stats --since 7d
mcp-shield audit stats --since 4w

# Export to JSON
mcp-shield audit export -f json -o audit.json

# Export to CSV
mcp-shield audit export -f csv -o audit.csv

# Use a custom database path (applies to all subcommands)
mcp-shield audit --db /path/to/audit.db show --last 20
mcp-shield audit --db /path/to/audit.db stats --since 7d

What it checks

22 checks across 3 suites, ~2 seconds per scan.

Compliance (COMP-001..010)

Check	What it verifies
COMP-001	MCP handshake (JSON-RPC initialize)
COMP-002	Server identity (name + version)
COMP-003	Valid inputSchema on all tools
COMP-004	Tool naming conventions
COMP-005	Ping/pong support
COMP-006	Tool descriptions present
COMP-007	Server capabilities declared
COMP-008	Schema field descriptions
COMP-009	Schema constraints (maxLength, pattern)
COMP-010	Resource/prompt validation

Security (SEC-001..007)

Check	What it detects	Severity	CWE
SEC-001	Tool poisoning (hidden instructions in descriptions)	critical	CWE-94
SEC-002	Injection vectors (path, URL, SQL, code fields)	high	CWE-78, CWE-89, CWE-22
SEC-003	Aggregated security score (0-100)	--	--
SEC-004	Dangerous operations (delete, exec, deploy)	high	CWE-78, CWE-250
SEC-005	Write scope (local vs cloud vs user-facing)	medium	CWE-434
SEC-006	Idempotency risk (non-retryable operations)	medium	CWE-352
SEC-007	Cost risk (cloud provisioning, paid APIs)	low	CWE-770

Advisory (ADV-001..005)

Informational only — does not affect the score.

Check	What it flags
ADV-001	Auth requirement hints (API key, OAuth)
ADV-002	External service dependencies (AWS, Stripe, GitHub)
ADV-003	Bulk operation warnings (unbounded arrays)
ADV-004	Sensitive data exposure (PII, credentials)
ADV-005	External network access (URL + fetch patterns)

Scoring

Composite score: 40% compliance + 60% security. Deductions per finding:

Severity	Deduction
critical	-25
high	-15
medium	-5
low	-2

Advisory checks are informational and do not affect the score.

Poisoning detection

Layer 1 — ~45 regex patterns across 11 categories:

Category	Examples
Instruction override	"ignore previous instructions", "new instructions:"
Role hijacking	"act as", "pretend to be", "you are now"
Format injection	ChatML <|im_start|>, Llama [INST], Handlebars {{#system}}
Data exfiltration	Markdown image exfil, "send to URL", credential reading
Hidden content	HTML comments, CSS display:none, ANSI escapes, zero-width Unicode
Hardcoded secrets	API keys (sk-live-*), GitHub PATs, Slack tokens
Agent injection	ReAct format injection, tool call injection

Layer 2 (opt-in, --ml) — DeBERTa-v3-base classifier for semantic detection.

ML dependencies (onnxruntime, tokenizers, huggingface-hub) are included in the default install. The --ml flag downloads the protectai/deberta-v3-base-prompt-injection-v2 ONNX model (~740 MB, cached in ~/.cache/mcp-shield/models/) on first use.

Why opt-in? The ML classifier can produce false positives on directive-like tool descriptions (e.g., "DEPRECATED: Use X instead" may be flagged as an injection). Use --ml when you want maximum detection sensitivity and can tolerate reviewing flagged results.

Risk classification

Every tool is classified into a risk tier:

Tier	Examples
read	read_file, list_directory, search
write_reversible	write_file, create_directory
write_external	send_email, deploy, webhook
write_sensitive	delete, exec, eval, drop

SARIF & GitHub Code Scanning

MCP Shield can output SARIF 2.1.0 reports — the standard format natively supported by GitHub's Security tab.

# Generate SARIF on stdout
mcp-shield test "npx server" --format sarif

# Save SARIF to file (works alongside any --format)
mcp-shield test "npx server" --sarif-output results.sarif

GitHub Actions integration

- name: Scan MCP server
  run: |
    pip install mcp-shield-cli
    mcp-shield test "npx -y @modelcontextprotocol/server-filesystem /tmp" \
      --sarif-output results.sarif \
      --fail-on high

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

SARIF output includes CWE references, CVSS-like severity scores, and logical locations (MCP tool names) — all visible in the GitHub Security tab.

Contributing

Contributions are welcome. Open an issue or submit a pull request.

git clone https://github.com/thuggeelya/mcp-shield.git
cd mcp-shield
pip install -e ".[dev]"
pytest

Author

thuggeelya

• LinkedIn: thuggeelya
• Telegram: @thuggeelya
• Email: [e-mail]

License

Apache 2.0