mcp-scan — CLI Security Scanner for MCP Servers

The MCP (Model Context Protocol) ecosystem is exploding. Hundreds of servers launching weekly — Dogpile Fetch, Lumonic, ExtraHop SOC, and countless community-built tools. Every AI agent now talks MCP. But security tooling for MCP servers is essentially non-existent.

Until today.

What mcp-scan Does

mcp-scan analyzes MCP server configurations and endpoints for 5 vulnerability classes across 10 security checks:

1. ANSI Escape Injection (ANSI-001)

The Brightsec-disclosed attack: ANSI escape sequences can hide malicious content from human reviewers while exposing it to AI agents. A tool description that looks clean in your terminal actually contains hidden instructions visible only to the LLM. mcp-scan detects all common ANSI escape patterns in tool descriptions, names, and response templates.

2. Over-Permissive Tool Definitions (PERM-001/002/003)

• Filesystem: Tools that accept unrestricted paths (/, **/*, no path prefix)
• Shell: Tools that execute arbitrary commands without an allowlist
• Network: Tools that can reach any host or port

3. Missing Input Validation (VAL-001/002)

Parameters that accept any type, or string parameters without pattern, enum, or length constraints — the classic injection entry point.

4. Prompt Injection Vectors (INJ-001/002)

Tool descriptions or system prompts that dynamically incorporate untrusted user input — the primary vector for prompt injection attacks.

5. Insecure Transport (TLS-001/002)

MCP endpoints using http:// instead of https://, or ws:// instead of wss://.

Quick Start

pip install mcp-scan

# Scan a config file
mcp-scan -c my_mcp_config.json

# Scan a remote endpoint
mcp-scan --url https://my-mcp-server.com/sse

# Generate a JSON report for CI pipelines
mcp-scan -c config.json -o json --output-file report.json

# Focus on high/critical severity only
mcp-scan -c config.json --severity high

Real Results

We ran mcp-scan against a deliberately vulnerable server to test detection:

Scan ID: 7d441d55 | checks=10 failures=8 warnings=6
ANSI-001  [HIGH]    ANSI escape injection in tool metadata
PERM-002  [CRITICAL] Unrestricted shell execution in tool
TLS-001   [HIGH]    MCP endpoint uses insecure HTTP transport
INJ-001   [HIGH]    Tool metadata dynamically templated
...

And against our Hermes config (the MCP server you’re reading this from):

Scan ID: 598ae793 | checks=10 passed=10 — clean

Architecture

CLI (click) → Scanner → Config Parser / Endpoint Connector
                  ↓
          Check Modules (each produces Finding[])
                  ↓
          Reporter (Rich table + JSON)

Each check is a standalone module. Adding new checks is a single-file operation — implement a function that returns Finding[] and register it.

Why This Matters Now

The MCP ecosystem is at a critical inflection point:

• MCP security is the hottest topic in the AI infrastructure space right now
• The first major vulnerability class (ANSI escape injection) was disclosed this week
• Perplexity open-sourced Bumblebee (an MCP config scanner) — validating the category
• There is currently no dedicated, standalone security audit tool for MCP servers

mcp-scan fills that gap. It’s pip-installable, CI-friendly, and designed to be the first tool you run before connecting a new MCP server to your agent pipeline.

What’s Next

The spec is already loaded in the Task Manager with more checks planned:

• Rate limit analysis on tool definitions
• Credential/key exposure detection in configs
• Dependency chain analysis (transitive MCP server trust)
• Integration with mcp-hub for community-shared security scores

—