MCPShield

Security scanner and runtime protection for MCP servers.

MCP is becoming the TCP/IP of AI agents. MCPShield makes sure it doesn't become the next Log4j.

MCPShield scans your MCP server configurations for the vulnerabilities in the OWASP MCP Top 10 and provides runtime middleware to enforce security policies on every tool call. It works without a running server — pure static analysis of your config files.

---

Install

pip install mcpshield

Quick Start

# Scan your Claude Desktop or Cursor MCP config (auto-detected)
mcpshield scan

# Scan a specific config
mcpshield scan --config ./claude_desktop_config.json

# Get a JSON report
mcpshield scan --format json --output report.json

Programmatic usage:

from mcpshield import scan

result = scan()
print(f"Score: {result.score}/100  ({result.rating})")
for finding in result.sorted_findings():
    print(f"[{finding.severity.value}] {finding.rule_id}: {finding.title}")

---

What It Detects

MCPShield covers all 10 categories of the OWASP MCP Top 10:

Rule	Severity	OWASP	Description
MCPS-001	CRITICAL	MCP01	Hardcoded API keys and secrets in env vars
MCPS-002	HIGH	MCP03	Filesystem server with access to / or ~/.ssh
MCPS-003	HIGH	MCP08	npx -y with unverified or unpinned packages
MCPS-004	CRITICAL	MCP04	Shell invocation enabling command injection
MCPS-005	HIGH	MCP05	HTTP/SSE server without authentication or TLS
MCPS-006	HIGH	MCP03	Wildcard tool permissions (files:*, admin:*)
MCPS-007	MEDIUM	MCP02	Tool descriptions with injection keywords or hidden Unicode
MCPS-008	MEDIUM	MCP10	URL parameters without domain allowlisting (SSRF)
MCPS-009	LOW	MCP09	Missing audit logging configuration
MCPS-010	HIGH	MCP06	Shared session memory without user isolation
MCPS-011	MEDIUM	MCP05	stdio server running without sandboxing
MCPS-012	CRITICAL	MCP08	Known CVE — mcp-remote, MCP Inspector, filesystem

---

CLI

# Scan auto-detected config
mcpshield scan

# Scan specific file
mcpshield scan --config ./mcp-config.json

# Output formats
mcpshield scan --format json --output report.json
mcpshield scan --format sarif --output report.sarif   # GitHub Security tab
mcpshield scan --format html --output report.html     # Shareable HTML

# Fail CI on critical/high findings
mcpshield scan --fail-on critical
mcpshield scan --fail-on high

# Skip specific rules
mcpshield scan --skip-rules MCPS-009,MCPS-011

# Check a package against the vulnerability database
mcpshield check-package mcp-remote
mcpshield check-package mcp-remote@0.1.7

# Generate a starter policy file
mcpshield init-policy --output policy.yaml

# Validate an existing policy
mcpshield validate-policy policy.yaml

---

Runtime Guard

Protect your MCP server's tool handlers at runtime with policy enforcement:

from mcpshield.runtime import MCPGuard, Policy

# Load security policy
policy = Policy.from_yaml("policy.yaml")

# Create guard
guard = MCPGuard(policy=policy)

# Protect tool handlers
@guard.protect
async def handle_tool_call(tool_name: str, arguments: dict) -> dict:
    # Blocked tools raise PolicyViolationError before reaching here
    # Path and domain restrictions are enforced automatically
    # Rate limits are checked per-tool
    ...

Policy File

# policy.yaml
version: "1.0"
rules:
  blocked_tools:
    - "execute_command"
    - "run_shell"

  tool_restrictions:
    filesystem_read:
      allowed_paths:
        - "/data/**"
        - "/public/**"
      blocked_paths:
        - "~/.ssh/**"
        - "~/.aws/**"
    http_request:
      allowed_domains:
        - "api.github.com"
      blocked_domains:
        - "169.254.169.254"  # AWS metadata
        - "localhost"

  rate_limits:
    default: 100/minute
    per_tool:
      database_query: 20/minute

  approval_required:
    - "delete_file"
    - "send_email"

  audit:
    enabled: true
    log_file: "mcpshield_audit.jsonl"
    log_level: "all"

---

CI/CD Integration

Add to .github/workflows/security.yml:

name: MCP Security Scan

on: [push, pull_request]

jobs:
  mcpshield:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install mcpshield
      - name: Scan MCP config
        run: mcpshield scan --config ./claude_desktop_config.json --fail-on high
      - name: Generate SARIF report
        run: mcpshield scan --config ./claude_desktop_config.json --format sarif --output mcpshield.sarif
      - name: Upload to GitHub Security tab
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: mcpshield.sarif

---

Writing Custom Rules

Extend BaseRule to add your own checks:

from mcpshield.scanner.rules.base import BaseRule
from mcpshield.scanner.finding import Finding, ServerConfig
from mcpshield.utils.severity import Severity

class MyCustomRule(BaseRule):
    rule_id = "CUSTOM-001"
    title = "My Security Check"
    owasp_mapping = "MCP01"

    def check(self, server: ServerConfig) -> list[Finding]:
        findings = []
        if "dangerous_pattern" in str(server.raw):
            findings.append(Finding(
                rule_id=self.rule_id,
                title=self.title,
                description="Dangerous pattern detected",
                severity=Severity.HIGH,
                owasp_mcp=self.owasp_mapping,
                server_name=server.name,
                location="config",
                remediation="Remove the dangerous pattern.",
                references=["https://owasp.org/www-project-mcp-top-10/"],
            ))
        return findings

# Use with the engine
from mcpshield.scanner.engine import ScanEngine
from mcpshield.scanner.rules import DEFAULT_RULES

engine = ScanEngine(rules=DEFAULT_RULES + [MyCustomRule])

---

Security Score

MCPShield computes a score from 0-100:

Score	Rating
90-100	EXCELLENT
70-89	GOOD
50-69	FAIR
25-49	POOR
0-24	CRITICAL

Each CRITICAL finding deducts 25 points, HIGH deducts 15, MEDIUM deducts 8, LOW deducts 3.

---

References

• OWASP MCP Top 10
• MCP Security Best Practices
• CVE-2025-6514 — mcp-remote command injection
• Model Context Protocol Specification

---

Contributing

Issues and pull requests welcome at github.com/aryanjp1/mcpshield.

To run the test suite:

pip install -e ".[dev]"
pytest --cov

To add a new rule, create a file in src/mcpshield/scanner/rules/, extend BaseRule, and add it to DEFAULT_RULES in src/mcpshield/scanner/rules/__init__.py.

---

License

MIT — see LICENSE.