cisco-ai-defense/mcp-scanner

What is MCP Scanner?

MCP Scanner is a Python‑based security tool that inspects Model Context Protocol (MCP) servers and the assets they expose – tools, prompts, resources, and even the server code itself. It combines three analysis engines:

Cisco AI Defense inspect API – a proprietary service that can evaluate MCP payloads.
YARA – classic pattern‑matching rules for known malicious code.
LLM‑based analysis – large‑language‑model prompts that reason about the safety of prompts, tools and code.

The result is a detailed security report that can be used locally, in CI/CD pipelines, or via a REST API.

Key Features (as described in the README)

Feature	What it does
Multiple operation modes	Run as a stand‑alone CLI (`mcp‑scanner`) or expose the scanner as a REST API (`mcp‑scanner‑api`).
Three‑engine analysis	Use YARA, the Cisco AI Defense API, and/or an LLM – together or individually.
Vulnerable‑package scanning	Integrates `pip‑audit` to flag known CVEs in Python dependencies.
Readiness scanning	Static checks for production‑grade concerns such as missing time‑outs or error handling.
Behavioural code scanning	Executes (in a Docker sandbox) or statically analyses source code of MCP servers to spot malicious behaviour.
VirusTotal binary scanning	Looks up SHA‑256 hashes of bundled files (images, PDFs, executables, archives) on VirusTotal.
PyPI & npm supply‑chain scanning	Downloads packages, runs them in an isolated Docker container, and analyses their behaviour.
Static/offline scanning	Accepts pre‑generated MCP JSON files – ideal for CI/CD or air‑gapped environments.
Fine‑grained authentication	Supports OAuth, bearer tokens, custom HTTP headers, and explicit API‑key configuration for Cisco AI Defense, LLM providers, and VirusTotal.
MCP 2.0 protocol support	Negotiates the upcoming `2026‑07‑28` protocol version, falling back to legacy handshakes automatically.
Custom YARA rules	Users can add their own rule sets to detect organization‑specific patterns.
Comprehensive reporting	Multiple output formats (summary, table, raw JSON, by‑tool) and a `--detailed` flag for deeper insight.

How to get it running

Prerequisites – Python 3.11+, the uv package manager, and optional API keys (Cisco AI Defense, an LLM provider, VirusTotal). The MCP Python SDK (mcp>=2.0.0) is bundled.
Installation – Either as a global tool:
```
uv tool install --python 3.13 cisco-ai-mcp-scanner
```
or from source with uv sync.

Configuration – Export environment variables for the services you want to use, e.g.:

export MCP_SCANNER_API_KEY=…          # Cisco AI Defense
export MCP_SCANNER_LLM_API_KEY=…      # OpenAI / Bedrock etc.
export VIRUSTOTAL_API_KEY=…           # VirusTotal

Run a quick scan – Example CLI command scanning a remote server with YARA only:

mcp-scanner --server-url https://mcp.example.com/mcp \
            --analyzers yara --format summary

Or launch the REST API:

mcp-scanner-api --host 0.0.0.0 --port 8080

Typical use‑cases

Scenario	Why MCP Scanner helps
Security audit of an internal LLM‑service	Checks both the MCP protocol implementation and the content of prompts/tools for hidden malicious behaviour.
Supply‑chain review of third‑party packages	`pypi‑scan` / `npm‑scan` download the package, sandbox it, and run behavioural analysis plus YARA checks.
CI/CD gate	Use the `static` subcommand on generated MCP JSON files to enforce safety before code is promoted.
Incident response	Quickly run `virustotal` on any binary bundled with a suspect MCP server.
Compliance	`vulnerable‑package` flags known CVEs in Python dependencies, complementing the LLM/YARA findings.

Limitations & considerations (from the README)

The LLM analyzer requires a paid API key (OpenAI, Bedrock, Azure, etc.) – the tool only sends prompts to the model; it does not host any model locally.
VirusTotal look‑ups need an API key; uploading files is optional and disabled by default for privacy.
Behavioural analysis of PyPI/npm packages runs inside Docker by default; disabling Docker (--no-docker) runs the code in‑process, which may be less isolated.
Scanning stdio‑based MCP servers may need a longer timeout (MCP_SCANNER_STDIO_TIMEOUT) if the server performs heavy start‑up work.
The tool focuses on security findings – it does not attempt to fix or remediate issues automatically.

Who might find this useful?

Security engineers protecting internal LLM‑backed services that expose MCP endpoints.
DevOps / CI teams that want an automated gate for supply‑chain safety of Python or JavaScript packages used by MCP servers.
Developers of MCP‑based applications who need to verify that their tools, prompts, and resources are not inadvertently malicious.
Red‑team / audit consultants looking for a quick way to combine YARA signatures, LLM reasoning, and Cisco’s AI‑Defense API against a target MCP deployment.

Bottom line

cisco-ai-mcp-scanner is a full‑featured, Python‑native security scanner tailored to the emerging Model Context Protocol ecosystem. By stitching together YARA, a commercial AI‑defense service, and LLM reasoning, it gives practitioners a single command‑line (or API) interface to assess the safety of MCP servers, their code, and the packages they depend on.