mcpshield-cli

MCPShield

Security scanner for MCP (Model Context Protocol) servers.

Scans live MCP servers for vulnerabilities, tool poisoning, prompt injection, credential leaks, and more. Maps findings to the OWASP MCP Top 10.

Why MCPShield?

The MCP ecosystem has 20,000+ servers with serious security problems:

• 82% of MCP servers are vulnerable to path traversal
• 53% use hardcoded static API keys
• 30+ CVEs filed in just 60 days (Jan-Feb 2026)
• 72.8% tool poisoning success rate on leading LLMs

Existing tools only scan static source code on GitHub. MCPShield scans live running servers -- the first runtime MCP security scanner.

Quick Start

# Scan a local MCP server
npx mcpshield scan --stdio "node your-server.js"

# Scan a remote MCP server
npx mcpshield scan --url https://your-server.com/mcp

# JSON output (for CI/CD)
npx mcpshield scan --stdio "node server.js" --json

# Only show critical and high severity
npx mcpshield scan --stdio "node server.js" --severity high

Installation

npm install -g mcpshield

Or use directly with npx:

npx mcpshield scan --stdio "node server.js"

What It Scans For

MCPShield runs 30+ security rules across 7 categories:

Prompt Injection (PI)

Rule	Severity	What It Detects
PI-001	High	Hidden Unicode characters (zero-width spaces, BOM)
PI-002	High	LLM injection markers ("ignore previous instructions", etc.)
PI-003	Medium	Base64/URL encoded payloads
PI-004	Medium	HTML entity obfuscation
PI-005	Medium	Whitespace smuggling with hidden instructions

Tool Poisoning (TP)

Rule	Severity	What It Detects
TP-001	High	Cross-tool references (tool shadowing setup)
TP-002	High	Behavioral manipulation ("always BCC", "secretly forward")
TP-003	Critical	Credentials in tool descriptions
TP-004	High	Environment variable access instructions
TP-005	High	Sensitive file path references (.ssh, .aws, .env)
TP-006	Critical	Exfiltration URLs/emails in descriptions
TP-007	High	Data harvesting instructions
TP-008	Medium	Tool name-description mismatch

Tool Shadowing (TS)

Rule	Severity	What It Detects
TS-001	Medium	Duplicate tool names
TS-002	Medium	Non-ASCII characters in tool names (homograph attacks)

Authentication (AUTH)

Rule	Severity	What It Detects
AUTH-001	Critical	No authentication on HTTP servers
AUTH-002	High	No TLS encryption
AUTH-003	Medium	Stdio transport auth limitations

Authorization (AUTHZ)

Rule	Severity	What It Detects
AUTHZ-001	Medium	Read-only annotation contradicts write behavior
AUTHZ-002	Medium	Missing destructive hint on delete/remove tools

Input Validation (IV)

Rule	Severity	What It Detects
IV-001	High	Command execution without sanitization
IV-002	High	Path traversal risk in file tools
IV-003	High	SQL injection risk
IV-004	High	SSRF risk in URL-accepting tools
IV-005	Medium	Unbounded string/array input sizes

Metadata & Configuration (META)

Rule	Severity	What It Detects
META-001	Low	Missing server version
META-002	Low	Missing server name
META-003	Info	Unusually large tool count
META-004	Low	Tools missing descriptions
META-005	Medium	Excessively long descriptions (hidden content)
META-006	Info	Server capabilities summary

OWASP MCP Top 10 Mapping

All findings map to the OWASP MCP Top 10:

OWASP Category	MCPShield Rules
MCP01: Token Mismanagement	TP-003, TP-004, AUTH-001, AUTH-002
MCP02: Tool Poisoning	TP-001, TP-002, TP-005, TP-006, TP-007, TP-008, TS-001, TS-002
MCP03: Insufficient Input Validation	IV-001, IV-002, IV-003, IV-004, IV-005
MCP06: Prompt Injection	PI-001, PI-002, PI-003, PI-004, PI-005
MCP07: Insufficient Auth & Authorization	AUTH-001, AUTH-002, AUTH-003, AUTHZ-001, AUTHZ-002

CLI Options

mcpshield scan [options]

Options:
  --stdio <command>   Scan a local stdio MCP server
  --url <url>         Scan a remote HTTP MCP server
  --json              Output results as JSON
  --severity <level>  Minimum severity: critical, high, medium, low, info (default: info)
  --timeout <ms>      Connection timeout in milliseconds (default: 30000)
  -h, --help          Display help

Exit Codes

Code	Meaning
0	Scan completed, no critical findings
1	Scan failed (connection error, timeout, etc.)
2	Scan completed, critical findings detected

Use exit code 2 in CI/CD pipelines to fail builds when critical vulnerabilities are found.

Scoring

MCPShield assigns a security score (0-100) and letter grade:

Grade	Score	Meaning
A	90-100	Excellent security posture
B	80-89	Good, minor issues only
C	70-79	Fair, some medium issues
D	50-69	Poor, significant issues
F	0-49	Critical security failures

Deductions: Critical = -25, High = -15, Medium = -8, Low = -3, Info = 0.

How It Works

MCPShield connects to MCP servers as a standard MCP client:

• Connect via stdio (local) or HTTP (remote) transport
• Enumerate all tools, resources, and prompts via listTools(), listResources(), listPrompts()
• Analyze every tool description, schema field, parameter, and annotation
• Score findings using CVSS-style severity levels
• Report with actionable remediation guidance

Safe by default -- MCPShield only reads metadata. It never calls your tools or modifies anything.

JSON Output

Use --json for machine-readable output:

{
  "serverInfo": { "name": "my-server", "version": "1.0.0" },
  "target": "node server.js",
  "transport": "stdio",
  "scanDate": "2026-04-06T15:30:00.000Z",
  "scanDurationMs": 327,
  "toolCount": 5,
  "resourceCount": 0,
  "promptCount": 0,
  "findings": [
    {
      "ruleId": "TP-003",
      "category": "Tool Poisoning",
      "severity": "critical",
      "title": "Credentials Referenced in Tool Description",
      "description": "Tool metadata references credentials or secrets...",
      "evidence": "Credential pattern: \"API_KEY\"",
      "location": "tool:query_db.description",
      "owaspCategory": "MCP01: Token Mismanagement",
      "remediation": "Never reference credentials in tool descriptions."
    }
  ],
  "score": 42,
  "grade": "D"
}

Contributing

MCPShield is open source under the MIT license. Contributions welcome.

git clone https://github.com/mcpshield/mcpshield.git
cd mcpshield
npm install
npm run build
npm test

License

MIT