Skip to content
Back to search

mcp-scanner

Scan MCP servers for potential threats & security findings.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cisco-ai-defense/mcp-scanner with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cisco-ai-defense/mcp-scanner'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cisco-ai-defense--mcp-scanner/badge.svg)](/listings/cisco-ai-defense--mcp-scanner)

HTML

<a href="/listings/cisco-ai-defense--mcp-scanner"><img src="/api/listings/cisco-ai-defense--mcp-scanner/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.11+ - uv (Python package manager) - A valid Cisco AI Defense API Key (optional) - LLM Provider API Key (optional) - VirusTotal API Key (optional, for binary file malware scanning)

Installing as a CLI tool

uv tool install --python 3.13 cisco-ai-mcp-scanner

Alternatively, you can install from source:

uv tool install --python 3.13 --from git+https://github.com/cisco-ai-defense/mcp-scanner cisco-ai-mcp-scanner

Installing for local development

git clone https://github.com/cisco-ai-defense/mcp-scanner
cd mcp-scanner
uv sync --python 3.13 

Install as a dependency in other projects

Add MCP Scanner as a dependency using uv. From your project root (initialize with uv if needed):

uv init --python 3.13 #if not already done
uv add cisco-ai-mcp-scanner
# then activate the virtual environment:
## macOS and Linux: source .venv/bin/activate
## Windows CMD: .venv\Scripts\activate
## Windows PWSH: .venv\Scripts\Activate.ps1
uv sync

The module name is `mcpscanner`. Import this module with:

# import everything (not recommended)
import mcpscanner

# selective imports (recommended). For example:
from mcpscanner import Config, Scanner
from mcpscanner.core.models import AnalyzerEnum

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 852 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCP Scanner
  2. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  3. [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
  4. [![PyPI](https://img.shields.io/pypi/v/cisco-ai-mcp-scanner.svg)](https://pypi.org/project/cisco-ai-mcp-scanner/)
  5. [![Discord](https://img.shields.io/badge/Discord-Join%20Us-7289DA?logo=discord&logoColor=white)](https://discord.com/invite/nKWtDcXxtx)
  6. [![Cisco AI Defense](https://img.shields.io/badge/Cisco-AI%20Defense-049fd9?logo=cisco&logoColor=white)](https://www.cisco.com/site/us/en/products/security/ai-defense/index.html)
  7. [![AI Security and Safety Framework](https://img.shields.io/badge/AI%20Security-Framework-orange)](https://learn-cloudsecurity.cisco.com/ai-security-framework)
  8. A Python tool for scanning MCP (Model Context Protocol) servers and tools for potential security findings. The MCP Scanner combines Cisco AI Defense inspect API, YARA rules and LLM-based analysis to detect malicious MCP tools.
  9. ## Overview
  10. The MCP Scanner provides a comprehensive solution for scanning MCP servers and tools for security findings. It leverages three powerful scanning engines (Yara, LLM-based analysis, Cisco AI Defense) that can be used together or independently.
  11. The SDK is designed to be easy to use while providing powerful scanning capabilities, flexible authentication options, and customization.
  12. ![MCP Scanner](https://github.com/cisco-ai-defense/mcp-scanner/raw/main/images/mcp_scanner.gif?raw=true)
  13. ## Features
  14. - **Multiple Modes:** Run scanner as a stand-alone CLI tool or REST API server
  15. - **Multi-Engine Security Analysis**: Use all three scanning engines together or independently based on your needs.
  16. - **Vulnerable Packages Scanning**: Scan Python dependencies for known vulnerabilities (CVE/PYSEC/GHSA) using pip-audit integration.
  17. - **Readiness Scanning**: Zero-dependency static analysis for production readiness issues (timeouts, retries, error handling).
  18. - **Comprehensive Scanning**: Scan MCP tools, prompts, resources, and server instructions for security findings
  19. - **Behavioural Code Scanning**: Scan Source code of MCP servers for finding threats.
  20. - **VirusTotal Binary Scanning**: Automatically detect malware in binary files (images, PDFs, executables, archives) bundled with MCP servers using VirusTotal hash lookups.
  21. - **PyPI Package Scanning**: Download and scan PyPI packages inside a Docker sandbox with behavioral analysis.
  22. - **Behavioural Code Scanning**: Scan Source code of MCP servers for detecting threats.
  23. - **Static/Offline Scanning**: Scan pre-generated JSON files without live server connections - perfect for CI/CD pipelines and air-gapped environments
  24. - **Explicit Authentication Control**: Fine-grained control over authentication with explicit Auth parameters.
  25. - **OAuth Support**: Full OAuth authentication support for both SSE and streamable HTTP connections.
  26. - **Custom Endpoints**: Configure the API endpoint to support any Cisco AI Defense environments.
  27. - **MCP Server Integration**: Connect directly to MCP servers to scan tools, prompts, and resources with flexible authentication.
  28. - **MCP 2.0 Protocol Support**: Negotiates modern protocol (`2026-07-28` via `server/discover`) with automatic fallback to legacy `initialize()` for older servers — remote HTTP/SSE and stdio.
  29. - **Customizable YARA Rules**: Add your own YARA rules to detect specific patterns.
  30. - **Comprehensive Reporting**: Detailed reports on detected security findings.
  31. ## Installation
  32. ### Prerequisites
  33. - Python 3.11+
  34. - uv (Python package manager)
  35. - **MCP Python SDK** (`mcp>=2.0.0`, bundled with this package). Live scans negotiate `2026-07-28` when the server supports it and fall back to legacy handshake versions automatically.
  36. - A valid Cisco AI Defense API Key (optional)
  37. - LLM Provider API Key (optional)
  38. - VirusTotal API Key (optional, for binary file malware scanning)
  39. ### Installing as a CLI tool
  40. ```bash
  41. uv tool install --python 3.13 cisco-ai-mcp-scanner
  42. ```
  43. Alternatively, you can install from source:
  44. ```bash
  45. uv tool install --python 3.13 --from git+https://github.com/cisco-ai-defense/mcp-scanner cisco-ai-mcp-scanner
  46. ```
  47. ### Installing for local development
  48. ```bash
  49. git clone https://github.com/cisco-ai-defense/mcp-scanner
  50. cd mcp-scanner
  51. uv sync --python 3.13
  52. ```
  53. ### MCP protocol compatibility
  54. Live scans (remote HTTP/SSE and stdio) negotiate the MCP protocol version automatically:
  55. 1. **Modern (mcp SDK ≥ 2.0):** The scanner calls `server/discover` first. Servers built with the current Python SDK (`MCPServer`) typically respond with protocol version **`2026-07-28`**.
  56. 2. **Legacy fallback:** If `discover` is unavailable or the server only supports handshake-era versions, the scanner falls back to **`initialize()`** (for example `2024-11-05`, `2025-06-18`, `2025-11-25`).
  57. 3. **Backward compatible:** Existing stdio and remote servers that predate mcp 2.0 continue to work without changes on the scanner side.
  58. The Python MCP 1.x stdio server reports an unknown `server/discover` request as
  59. a generic `-32602` invalid-parameters error. The scanner retries `initialize()`
  60. for that specific stdio error shape and logs a warning. Other `-32602` errors
  61. surface to the caller so malformed modern discovery is not silently downgraded.
  62. Example servers under `examples/` and eval fixtures use **`MCPServer`** from `mcp.server.mcpserver` (mcp 2.0). The static/behavioral analyzers still recognize **legacy `FastMCP` patterns** in third-party source code for capability extraction.
  63. Integration tests: `uv run pytest tests/test_stdio_modern_integration.py tests/test_scanner.py -k negotiate`
  64. For an unauthenticated HTTP endpoint, run read-only wire-protocol probes with
  65. `mcp-scanner protocol --server-url https://your-server.example/mcp`. This checks
  66. modern request envelope headers on servers advertising `2026-07-28` and runs
  67. safe legacy checks for older endpoints. It does not call tools or prove
  68. that unauthenticated callers can invoke them. A protected endpoint may require
  69. separate authorized testing to assess its behavior after authentication.
  70. The opt-in `schema` analyzer classifies nested `$ref` values in advertised
  71. tool input and output schemas. Use `--analyzers schema` to run this check,
  72. including with the `static --tools` mode. See
  73. [MCP 2.0 threat coverage](docs/mcp-2-threat-coverage.md)
  74. for the scan-time and runtime boundary.
  75. ### Install as a dependency in other projects
  76. Add MCP Scanner as a dependency using uv. From your project root (initialize with uv if needed):
  77. ```bash
  78. uv init --python 3.13 #if not already done
  79. uv add cisco-ai-mcp-scanner
  80. # then activate the virtual environment:
  81. ## macOS and Linux: source .venv/bin/activate
  82. ## Windows CMD: .venv\Scripts\activate
  83. ## Windows PWSH: .venv\Scripts\Activate.ps1
  84. uv sync
  85. ```
  86. The module name is `mcpscanner`. Import this module with:
  87. ```python
  88. # import everything (not recommended)
  89. import mcpscanner
  90. # selective imports (recommended). For example:
  91. from mcpscanner import Config, Scanner
  92. from mcpscanner.core.models import AnalyzerEnum
  93. ```
  94. ## Quick Start
  95. ### Environment Setup
  96. #### Core API Configuration
  97. ```bash
  98. Cisco AI Defense API (only required for API analyzer)
  99. export MCP_SCANNER_API_KEY="your_cisco_api_key"
  100. export MCP_SCANNER_ENDPOINT="https://us.api.inspect.aidefense.security.cisco.com/api/v1"
  101. # For other endpoints please visit https://developer.cisco.com/docs/ai-defense/getting-started/#base-url
  102. ```
  103. #### LLM Configuration (for LLM analyzer and Code Behavioral Analyzer)
  104. **Tested LLMs:** OpenAI GPT-4o and GPT-4.1 | AWS Bedrock Claude 4.5 Sonnet
  105. ```bash
  106. # AWS Bedrock Claude with AWS credentials (profile)
  107. export AWS_PROFILE="your-profile"
  108. export AWS_REGION="us-east-1"
  109. export MCP_SCANNER_LLM_MODEL="bedrock/anthropic.claude-sonnet-4-5-20250929-v2:0" # Any AWS Bedrock supported model
  110. # AWS Bedrock Claude with API key (Bearer token)
  111. export MCP_SCANNER_LLM_API_KEY="bedrock-api-key-..." # Generated via Amazon Bedrock -> API Keys
  112. export AWS_REGION="us-east-1"
  113. export MCP_SCANNER_LLM_MODEL="bedrock/us.anthropic.claude-sonnet-4-5-20250929-v2:0" # Any AWS Bedrock supported model
  114. # LLM Provider API Key (required for LLM analyzer)
  115. export MCP_SCANNER_LLM_API_KEY="your_llm_api_key" # OpenAI
  116. # LLM Model Configuration (optional - defaults provided)
  117. export MCP_SCANNER_LLM_MODEL="gpt-5.2" # Any LiteLLM-supported model
  118. export MCP_SCANNER_LLM_BASE_URL="https://api.openai.com/v1" # Custom LLM endpoint
  119. export MCP_SCANNER_LLM_API_VERSION="2025-04-01-preview" # API version (if required)
  120. # For Azure OpenAI (example)
  121. export MCP_SCANNER_LLM_BASE_URL="https://your-resource.openai.azure.com/"
  122. export MCP_SCANNER_LLM_API_VERSION="2025-04-01-preview"
  123. export MCP_SCANNER_LLM_MODEL="azure/gpt-5.2"
  124. # For Extended Thinking Models (longer timeout)
  125. export MCP_SCANNER_LLM_TIMEOUT=300
  126. ```
  127. Note: If you are using models from Azure Foundry, set the MCP_SCANNER_LLM_BASE_URL and MCP_SCANNER_LLM_MODEL environment variables, as Microsoft has deprecated the need for MCP_SCANNER_LLM_API_VERSION.
  128. #### VirusTotal Configuration (for file/directory malware scanning)
  129. The VirusTotal analyzer scans files and directories against VirusTotal's malware database using SHA256 hash lookups. It runs as a standalone analyzer via the `virustotal` subcommand or as part of `--analyzers virustotal`.
  130. ```bash
  131. # VirusTotal API key (get one free at https://www.virustotal.com/)
  132. export VIRUSTOTAL_API_KEY="your_virustotal_api_key"
  133. # Optional: explicitly disable VirusTotal scanning even when API key is present.
  134. # When not set, scanning is auto-enabled if VIRUSTOTAL_API_KEY is configured.
  135. # Set to "false" to skip VT scanning without removing the API key (e.g. in CI).
  136. export MCP_SCANNER_VIRUSTOTAL_ENABLED=false
  137. # Optional: Upload unknown files to VirusTotal for scanning (default: false, privacy-friendly)
  138. export MCP_SCANNER_VIRUSTOTAL_UPLOAD_FILES=false
  139. # Optional: Max files to scan per directory (default: 10, set to 0 for unlimited)
  140. export MCP_SCANNER_VT_MAX_FILES=10
  141. ```
  142. > **Note:** Without `VIRUSTOTAL_API_KEY`, files will not be scanned for malware. When enabled, the analyzer uses configurable inclusion/exclusion extension lists to determine which files to scan, skipping `__pycache__` and hidden directories.
  143. #### Stdio Connection Timeout
  144. When scanning stdio MCP servers, the scanner waits for the server process to start and respond. The default timeout is 60 seconds, which may be insufficient for servers that download large dependencies on first run. This setting only affects the stdio server connection; LLM/API call timeouts are controlled separately via `MCP_SCANNER_LLM_TIMEOUT`.
  145. ```bash
  146. # Increase stdio server startup timeout (default: 60 seconds)
  147. export MCP_SCANNER_STDIO_TIMEOUT=180 # 3 minutes — useful for servers with heavy deps
  148. # Or use the CLI flag (overrides the environment variable)
  149. mcp-scanner --stdio-timeout 180 stdio --stdio-command uvx --stdio-arg mcp-clickhouse
  150. ```
  151. #### Using a Local LLM (No API Key Required)
  152. If you are using a local LLM endpoint such as Ollama, vLLM, or LocalAI,
  153. the `MCP_SCANNER_LLM_API_KEY` variable is still required but can be set to any value.
  154. Example:
  155. ```bash
  156. export MCP_SCANNER_LLM_API_KEY=test
  157. export MCP_SCANNER_LLM_ENDPOINT=http://localhost:11434
  158. ```
  159. ### Quick Start Examples
  160. The fastest way to get started is using the `mcp-scanner` CLI command. Global flags (like `--analyzers`, `--format`, etc.) must be placed before a subcommand.
  161. #### CLI Usage
  162. ```bash
  163. # Scan well-known client configs on this machine
  164. mcp-scanner --scan-known-configs --analyzers yara --format summary
  165. # Stdio server (example using uvx mcp-server-fetch)
  166. mcp-scanner --stdio-command uvx --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch --analyzers yara --format summary
  167. # Remote server (deepwiki example)
  168. mcp-scanner --server-url https://mcp.deepwiki.com/mcp --analyzers yara --format summary
  169. # Suppress all output below ERROR (useful in CI/CD)
  170. mcp-scanner --log-level error --analyzers yara --format raw --server-url https://mcp.deepwiki.com/mcp
  171. # MCP Scanner as REST API
  172. mcp-scanner-api --host 0.0.0.0 --port 8080
  173. ```
  174. #### SDK Usage
  175. ```python
  176. import asyncio
  177. import os
  178. from mcpscanner import Config, Scanner, set_log_level
  179. from mcpscanner.core.models import AnalyzerEnum
  180. import logging
  181. async def main():
  182. # Suppress all mcpscanner logs below ERROR
  183. set_log_level(logging.ERROR)
  184. # Create configuration with your API keys
  185. config = Config(
  186. api_key="your_cisco_api_key",
  187. llm_provider_api_key="your_llm_api_key"
  188. )
  189. # Create scanner
  190. scanner = Scanner(config)
  191. # Scan all tools on a remote server
  192. tool_results = await scanner.scan_remote_server_tools(
  193. "https://mcp.deepwiki.com/mcp",
  194. analyzers=[AnalyzerEnum.API, AnalyzerEnum.YARA, AnalyzerEnum.LLM]
  195. )
  196. # Print tool results
  197. for result in tool_results:
  198. print(f"Tool: {result.tool_name}, Safe: {result.is_safe}")
  199. # Scan all prompts on a server
  200. prompt_results = await scanner.scan_remote_server_prompts(
  201. "http://127.0.0.1:8000/mcp",
  202. analyzers=[AnalyzerEnum.LLM]
  203. )
  204. # Print prompt results
  205. for result in prompt_results:
  206. print(f"Prompt: {result.prompt_name}, Safe: {result.is_safe}")
  207. # Scan all resources on a server
  208. resource_results = await scanner.scan_remote_server_resources(
  209. "http://127.0.0.1:8000/mcp",
  210. analyzers=[AnalyzerEnum.LLM],
  211. allowed_mime_types=["text/plain", "text/html"]
  212. )
  213. # Print resource results
  214. for result in resource_results:
  215. print(f"Resource: {result.resource_name}, Safe: {result.is_safe}, Status: {result.status}")
  216. # Scan a stdio server while suppressing its stderr output
  217. from mcpscanner.core.mcp_models import StdioServer
  218. server = StdioServer(command="uvx", args=["mcp-server-fetch"])
  219. with open(os.devnull, "w") as devnull:
  220. stdio_results = await scanner.scan_stdio_server_tools(
  221. server,
  222. analyzers=[AnalyzerEnum.YARA],
  223. errlog=devnull
  224. )
  225. # Run the scanner
  226. asyncio.run(main())
  227. ```
  228. #### Subcommands Overview
  229. - **remote**: scan a remote MCP server (SSE or streamable HTTP). Supports `--server-url`, optional `--bearer-token`, `--header`.
  230. - **stdio**: launch and scan a stdio MCP server. Requires `--stdio-command`; accepts `--stdio-args`, `--stdio-env`, optional `--stdio-tool`, `--stdio-timeout`.
  231. - **config**: scan servers from a specific MCP config file. Requires `--config-path`; optional `--bearer-token`, `--stderr-file`.
  232. - **known-configs**: scan servers from well-known client config locations on this machine; optional `--bearer-token`, `--stderr-file`.
  233. - **prompts**: scan prompts on an MCP server. Requires `--server-url`; optional `--prompt-name`, `--bearer-token`, `--header`.
  234. - **resources**: scan resources on an MCP server. Requires `--server-url`; optional `--resource-uri`, `--mime-types`, `--bearer-token`, `--header`.
  235. - **instructions**: scan server instructions from the connect handshake (`DiscoverResult` on mcp 2.0, `InitializeResult` on legacy servers). Requires `--server-url`; optional `--bearer-token`.
  236. - **virustotal**: scan files or directories for malware using VirusTotal hash lookups. Requires a `scan_path` argument (file or directory).
  237. - **pypi-scan**: download and scan a PyPI package with behavioral analysis. Docker-sandboxed by default; pass `--no-docker` (or `use_docker=False` in the SDK) to run in-process — package code is never executed in either mode.
  238. - **npm-scan**: download and scan an npm package with full behavioral analysis on JavaScript / TypeScript sources. Docker-sandboxed by default; supports `--no-docker` for SDK / CI environments.
  239. - **supplychain**: scan source code of an MCP server for Behavioural analysis. Requires path to MCP Server source code or source file.
  240. - **vulnerable-package**: scan Python dependencies for known vulnerabilities using pip-audit. Requires a path to a requirements file or project directory.
  241. - **static**: scan pre-generated MCP JSON files offline (CI/CD mode). Supports `--tools`, `--prompts`, `--resources`, optional `--mime-types`.
  242. Note: Top-level flags (e.g., `--server-url`, `--stdio-*`, `--config-path`, `--scan-known-configs`) remain supported when no subcommand is used, but subcommands are recommended.
  243. #### Additional Examples
  244. #### Scan well-known MCP config paths (Windsurf, Cursor, Claude, VS Code)
  245. ```bash
  246. # YARA-only scan of all servers defined in well-known config locations
  247. mcp-scanner --scan-known-configs --analyzers yara --format summary
  248. # Detailed output
  249. mcp-scanner --scan-known-configs --analyzers yara --detailed
  250. ```
  251. #### Scan a specific MCP config file
  252. ```bash
  253. # Expand ~ yourself if needed by your shell
  254. mcp-scanner --config-path "$HOME/.codeium/windsurf/mcp_config.json" \
  255. --analyzers yara --format by_tool
  256. ```
  257. #### Scan a stdio MCP server
  258. ```bash
  259. # Use repeated --stdio-arg for reliable argument passing
  260. mcp-scanner --analyzers yara --format summary \
  261. stdio --stdio-command uvx \
  262. --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch
  263. # Or list-form (ensure it doesn't conflict with later flags)
  264. mcp-scanner --analyzers yara --detailed \
  265. stdio --stdio-command uvx \
  266. --stdio-args --from mcp-server-fetch mcp-server-fetch
  267. # Scan only a specific tool on the stdio server
  268. mcp-scanner --analyzers yara --format summary \
  269. stdio --stdio-command uvx \
  270. --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch \
  271. --stdio-tool fetch
  272. # Increase startup timeout for servers with heavy dependencies (default: 60s)
  273. mcp-scanner --stdio-timeout 180 --analyzers yara --format summary \
  274. stdio --stdio-command uvx --stdio-arg mcp-clickhouse@0.1.13
  275. ```
  276. #### Use a Bearer token with remote servers (non-OAuth)
  277. ```bash
  278. # Direct remote server with Bearer token
  279. mcp-scanner --analyzers yara --format summary \
  280. remote --server-url https://your-mcp-server/sse --bearer-token "$TOKEN"
  281. # Apply Bearer token to all remote servers discovered from configs
  282. mcp-scanner --analyzers yara --detailed known-configs --bearer-token "$TOKEN"
  283. mcp-scanner --analyzers yara --format by_tool \
  284. config --config-path "$HOME/.codeium/windsurf/mcp_config.json" --bearer-token "$TOKEN"
  285. ```
  286. #### Use custom HTTP headers (e.g., MCP Gateway dual-token auth)
  287. ```bash
  288. # Single custom header
  289. mcp-scanner --analyzers yara remote --server-url https://your-mcp-server/mcp \
  290. --header "X-API-Key: your-api-key"
  291. # Multiple custom headers (MCP Gateway dual-token authentication)
  292. mcp-scanner --analyzers yara remote --server-url https://gateway.example.com/mcp \
  293. --header "Authorization: Bearer ingress-token" \
  294. --header "X-Egress-Auth: Bearer egress-token"
  295. ```
  296. > **Note:** Avoid specifying the same header via both `--bearer-token` and `--header`. If you use both `--bearer-token` and `--header "Authorization: Bearer <token>"`, the custom header value will be used (custom headers are applied last and override any duplicates).
  297. #### Scan Prompts
  298. ```bash
  299. # Scan all prompts on an MCP server
  300. mcp-scanner --analyzers llm prompts --server-url http://127.0.0.1:8000/mcp
  301. # Scan all prompts with detailed output
  302. mcp-scanner --analyzers llm --detailed prompts --server-url http://127.0.0.1:8000/mcp
  303. # Scan all prompts with table format
  304. mcp-scanner --analyzers llm --format table prompts --server-url http://127.0.0.1:8000/mcp
  305. # Scan a specific prompt by name
  306. mcp-scanner --analyzers llm prompts --server-url http://127.0.0.1:8000/mcp --prompt-name "greet_user"
  307. # Get raw JSON output
  308. mcp-scanner --analyzers llm --raw prompts --server-url http://127.0.0.1:8000/mcp
  309. ```
  310. #### Scan Resources
  311. ```bash
  312. # Scan all resources on an MCP server
  313. mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp
  314. # Scan all resources with detailed output
  315. mcp-scanner --analyzers llm --detailed resources --server-url http://127.0.0.1:8000/mcp
  316. # Scan all resources with table format
  317. mcp-scanner --analyzers llm --format table resources --server-url http://127.0.0.1:8000/mcp
  318. # Scan a specific resource by URI
  319. mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp \
  320. --resource-uri "file://test/document.txt"
  321. # Scan with custom MIME type filtering
  322. mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp \
  323. --mime-types "text/plain,text/html,application/json"
  324. ```
  325. #### Scan Server Instructions
  326. Server instructions provide usage guidelines, security notes, and configuration details returned during MCP session setup (`DiscoverResult` on modern servers, `InitializeResult` on legacy servers). Scanning instructions helps detect prompt injection, tool poisoning, and misleading guidance.
  327. ```bash
  328. # Scan server instructions (defaults to API, YARA, and LLM analyzers)
  329. mcp-scanner instructions --server-url http://127.0.0.1:8000/mcp
  330. # Scan with detailed output
  331. mcp-scanner --detailed instructions --server-url http://127.0.0.1:8000/mcp
  332. # Scan with specific analyzers (LLM recommended for semantic analysis)
  333. mcp-scanner --analyzers llm instructions --server-url http://127.0.0.1:8000/mcp
  334. # Get raw JSON output
  335. mcp-scanner --raw instructions --server-url http://127.0.0.1:8000/mcp
  336. # With authentication
  337. mcp-scanner instructions --server-url https://your-server.com/mcp --bearer-token "$TOKEN"
  338. ```
  339. #### VirusTotal Malware Scanning
  340. The VirusTotal analyzer scans files and directories against VirusTotal's malware database using SHA256 hash lookups. It supports configurable inclusion/exclusion extension lists and a per-directory file limit.
  341. ```bash
  342. # Scan a single file
  343. mcp-scanner virustotal /path/to/suspicious_file.exe
  344. # Scan a directory
  345. mcp-scanner virustotal /path/to/mcp_server_package/
  346. # With detailed output
  347. mcp-scanner virustotal /path/to/mcp_server_package/ --format detailed
  348. # Table format
  349. mcp-scanner virustotal /path/to/mcp_server_package/ --format table
  350. # Save results to file
  351. mcp-scanner virustotal /path/to/file.bin --output vt_results.json --format raw
  352. ```
  353. > **Note:** Requires `VIRUSTOTAL_API_KEY` environment variable. Free tier allows 4 requests/minute and 500 requests/day.
  354. #### Behavioral Code Scanning (Multi-Language)
  355. The Behavioral Analyzer performs advanced static analysis of MCP server source code to detect behavioral mismatches between docstring claims and actual implementation. It uses LLM-powered alignment checking combined with cross-file dataflow tracking.
  356. **Supported Languages:** Python, TypeScript, JavaScript, Go, Java, Kotlin, C#, Rust, Ruby, PHP
  357. ```bash
  358. # Scan a single file (any supported language)
  359. mcp-scanner behavioral /path/to/mcp_server.py
  360. mcp-scanner behavioral /path/to/server.ts
  361. mcp-scanner behavioral /path/to/server.go
  362. mcp-scanner behavioral /path/to/McpService.java
  363. mcp-scanner behavioral /path/to/server.kt
  364. mcp-scanner behavioral /path/to/Tools.cs
  365. mcp-scanner behavioral /path/to/server.rs
  366. # Scan a directory (auto-detects language by extension)
  367. mcp-scanner behavioral /path/to/mcp_servers/
  368. # With specific output format
  369. mcp-scanner behavioral /path/to/mcp_server.py --format by_severity
  370. # Detailed analysis with all findings
  371. mcp-scanner behavioral /path/to/mcp_server.py --format detailed
  372. # Save results to file
  373. mcp-scanner behavioral /path/to/mcp_server.py --output results.json --format raw
  374. ```
  375. See [Behavioral Scanning Documentation](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/behavioral-scanning.md) for complete technical details.
  376. #### PyPI Package Scanning
  377. Download and scan PyPI packages with behavioral analysis to detect hidden behaviors like data exfiltration, backdoors, and prompt injection. Docker-sandboxed by default; pass `--no-docker` for SDK / CI environments — package code is never executed in either mode.
  378. ```bash
  379. # Scan a package (latest version)
  380. mcp-scanner pypi-scan flask
  381. # Scan a specific version
  382. mcp-scanner pypi-scan requests --version 2.31.0
  383. # Save results
  384. mcp-scanner pypi-scan fastapi -o results.json --format detailed
  385. # Force rebuild the Docker image
  386. mcp-scanner pypi-scan flask --rebuild-image
  387. ```
  388. See [PyPI Scanning Documentation](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/pypi-scanning.md) for complete details.
  389. #### Scan an npm Package
  390. ```bash
  391. # Scan latest version (Docker-sandboxed)
  392. mcp-scanner npm-scan @modelcontextprotocol/server-everything
  393. # Specific version
  394. mcp-scanner npm-scan my-mcp-server --version 1.2.3
  395. # No-Docker SDK / CI runner mode
  396. mcp-scanner npm-scan my-mcp-server --no-docker
  397. ```
  398. See [npm Scanning Documentation](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/npm-scanning.md) for complete details.
  399. #### Vulnerable Packages Scanning
  400. The Vulnerable Packages Analyzer scans Python dependencies for known security vulnerabilities (CVE, PYSEC, GHSA) using pip-audit. It requires no API keys and works with requirements files or project directories.
  401. ```bash
  402. # Scan a requirements file
  403. mcp-scanner vulnerable-package /path/to/requirements.txt
  404. # Scan a project directory (auto-detects requirements.txt or pyproject.toml)
  405. mcp-scanner vulnerable-package /path/to/project/
  406. # Use OSV vulnerability service instead of PyPI
  407. mcp-scanner vulnerable-package /path/to/requirements.txt --vulnerability-service osv
  408. # Detailed output with full vulnerability descriptions
  409. mcp-scanner vulnerable-package /path/to/requirements.txt --format detailed
  410. # Save results to file
  411. mcp-scanner vulnerable-package /path/to/requirements.txt --output results.json --format raw
  412. # Automatically fix vulnerable dependencies
  413. mcp-scanner vulnerable-package /path/to/requirements.txt --fix
  414. ```
  415. Each vulnerability is mapped to the Cisco AI Threat Security Taxonomy under **AITech-9.3 / AISubtech-9.3.1 (Malicious Package / Tool Injection)**.
  416. #### Scan Static/Offline Files (CI/CD Mode)
  417. The `static` subcommand allows you to scan pre-generated JSON files without connecting to a live MCP server. This is ideal for CI/CD pipelines, air-gapped environments, or reproducible security checks.
  418. ```bash
  419. # Scan tools from a static JSON file
  420. mcp-scanner --analyzers yara static --tools /path/to/tools-list.json
  421. # Scan with multiple analyzers
  422. mcp-scanner --analyzers yara,llm static --tools /path/to/tools-list.json
  423. # Scan prompts from a static JSON file
  424. mcp-scanner --analyzers llm static --prompts /path/to/prompts-list.json
  425. # Scan resources from a static JSON file
  426. mcp-scanner --analyzers llm static --resources /path/to/resources-list.json
  427. # Scan all three types at once with detailed output
  428. mcp-scanner \
  429. --analyzers yara,llm,api \
  430. --format detailed \
  431. static \
  432. --tools /path/to/tools-list.json \
  433. --prompts /path/to/prompts-list.json \
  434. --resources /path/to/resources-list.json
  435. # CI/CD example: YARA-only scan (no API keys needed)
  436. mcp-scanner --analyzers yara --format summary static --tools output/tools.json
  437. ```
  438. **Expected JSON Format:**
  439. ```json
  440. {
  441. "tools": [
  442. {
  443. "name": "tool_name",
  444. "description": "Tool description",
  445. "inputSchema": { "type": "object", "properties": {} }
  446. }
  447. ]
  448. }
  449. ```
  450. For resources, static scanning accepts either `resources/list` metadata or a
  451. `resources/read` content snapshot:
  452. ```json
  453. {
  454. "contents": [
  455. {
  456. "uri": "file:///path/to/document.txt",
  457. "mimeType": "text/plain",
  458. "text": "Resource contents to scan"
  459. }
  460. ]
  461. }
  462. ```
  463. For more details, see [Static Scanning Documentation](docs/static-scanning.md) and [examples/static_scanning_example.py](examples/static_scanning_example.py).
  464. #### Readiness Scanning
  465. The Readiness Analyzer checks MCP tools for production readiness issues using 20 heuristic rules. It requires no API keys and focuses on operational reliability: timeouts, retries, error handling, and more.
  466. ```bash
  467. # Readiness-only scan (no API keys required)
  468. mcp-scanner --analyzers readiness --server-url http://localhost:8000/mcp
  469. # Combined security + readiness scan
  470. mcp-scanner --analyzers yara,readiness --server-url http://localhost:8000/mcp
  471. # Detailed readiness output
  472. mcp-scanner --analyzers readiness --detailed --server-url http://localhost:8000/mcp
  473. ```
  474. See [Readiness Scanning Documentation](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/readiness-scanning.md) for complete technical details.
  475. ### Prompt Defense Scanning
  476. The Prompt Defense Analyzer checks MCP tool descriptions and system prompts for **missing** defensive measures against 12 common attack vectors. It is pure regex — no API key or external dependencies required — and always runs by default.
  477. **Attack vectors checked:**
  478. 1. Instruction Override (HIGH)
  479. 2. Data Leakage (HIGH)
  480. 3. Role Escape (HIGH)
  481. 4. Indirect Injection (HIGH)
  482. 5. Output Weaponization (HIGH)
  483. 6. Output Manipulation (MEDIUM)
  484. 7. Multilingual Bypass (MEDIUM)
  485. 8. Unicode/Homoglyph Attack (MEDIUM)
  486. 9. Context Overflow (MEDIUM)
  487. 10. Social Engineering (MEDIUM)
  488. 11. Input Validation (MEDIUM)
  489. 12. Abuse Prevention (LOW)
  490. ```bash
  491. # Prompt defense scan only (no API keys required)
  492. mcp-scanner --analyzers prompt_defense --server-url http://localhost:8000/mcp
  493. # Combined security + prompt defense scan
  494. mcp-scanner --analyzers yara,prompt_defense --server-url http://localhost:8000/mcp
  495. ```
  496. Each missing defense maps to MCP Taxonomy codes (AITech / AISubtech) for standardized reporting.
  497. ### Logging Control
  498. By default the CLI shows `WARNING`-level output (or `DEBUG` with `--verbose`). For finer control use `--log-level`:
  499. ```bash
  500. # Show only errors (good for CI/CD)
  501. mcp-scanner --log-level error --analyzers yara --format raw --server-url https://mcp.deepwiki.com/mcp
  502. # Show warnings and above
  503. mcp-scanner --log-level warning --analyzers yara --format summary --scan-known-configs
  504. # Full debug output (equivalent to --verbose)
  505. mcp-scanner --log-level debug --analyzers yara --server-url https://mcp.deepwiki.com/mcp
  506. ```
  507. `--log-level` takes precedence over `--verbose` when both are provided.
  508. #### Library Log Level (SDK)
  509. Library consumers can control the log level programmatically. Unlike
  510. `logging.getLogger("mcpscanner").setLevel(...)`, which does not propagate
  511. to child loggers, `set_log_level` updates **every** mcpscanner logger and
  512. handler:
  513. ```python
  514. import logging
  515. from mcpscanner import set_log_level
  516. set_log_level(logging.ERROR) # suppress everything below ERROR
  517. set_log_level(logging.DEBUG) # show all debug output
  518. ```
  519. #### Suppressing Stdio Server Stderr
  520. MCP servers launched via stdio may emit noisy output to stderr (startup
  521. banners, dependency logs, etc.). All stdio scan methods accept an `errlog`
  522. parameter to redirect or suppress this output:
  523. ```python
  524. import os
  525. from mcpscanner import Scanner, Config
  526. from mcpscanner.core.mcp_models import StdioServer
  527. scanner = Scanner(Config())
  528. server = StdioServer(command="uvx", args=["mcp-server-fetch"])
  529. with open(os.devnull, "w") as devnull:
  530. results = await scanner.scan_stdio_server_tools(server, errlog=devnull)
  531. prompts = await scanner.scan_stdio_server_prompts(server, errlog=devnull)
  532. ```
  533. The `errlog` parameter is supported on `scan_stdio_server_tools`,
  534. `scan_stdio_server_tool`, `scan_stdio_server_prompts`,
  535. `scan_stdio_server_prompt`, `scan_well_known_mcp_configs`, and
  536. `scan_mcp_config_file`.
  537. ### API Server Usage
  538. The API server provides a REST interface to the MCP scanner functionality, allowing you to integrate security scanning into web applications, CI/CD pipelines, or other services. It exposes the same scanning capabilities as the CLI tool but through HTTP endpoints.
  539. ```bash
  540. # Start the API server (loads configuration from .env file)
  541. mcp-scanner-api --port 8000
  542. # Or with custom host and port
  543. mcp-scanner-api --host 0.0.0.0 --port 8080
  544. # Enable development mode with auto-reload
  545. mcp-scanner-api --reload
  546. ```
  547. Once running, the API server provides endpoints for:
  548. - **`/scan-tool`** - Scan a specific tool on an MCP server
  549. - **`/scan-all-tools`** - Scan all tools on an MCP server
  550. - **`/scan-prompt`** - Scan a specific prompt on an MCP server
  551. - **`/scan-all-prompts`** - Scan all prompts on an MCP server
  552. - **`/scan-resource`** - Scan a specific resource on an MCP server
  553. - **`/scan-all-resources`** - Scan all resources on an MCP server
  554. - **`/scan-instructions`** - Scan server instructions from the MCP connect handshake
  555. - **`/health`** - Health check endpoint
  556. Documentation is available in [docs/api-reference.md](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/api-reference.md) or as interactive documentation at `http://localhost:8000/docs` when the server is running.
  557. ## Output Formats
  558. The scanner supports multiple output formats:
  559. - **`summary`**: Concise overview with key findings
  560. - **`detailed`**: Comprehensive analysis with full findings breakdown
  561. - **`table`**: Clean tabular format
  562. - **`by_severity`**: Results grouped by severity level
  563. - **`raw`**: Raw JSON output
  564. ### Example Output
  565. #### Detailed Format
  566. ```bash
  567. mcp-scanner --server-url http://127.0.0.1:8001/sse --format detailed
  568. ```
  569. ```
  570. === MCP Scanner Detailed Results ===
  571. Scan Target: http://127.0.0.1:8001/sse
  572. Tool: execute_system_command
  573. Status: completed
  574. Safe: No
  575. Analyzer Results:
  576. • api_analyzer:
  577. - Severity: HIGH
  578. - Threat Summary: Detected 1 threat: security violation
  579. - Threat Names: SECURITY VIOLATION
  580. - Total Findings: 1
  581. • yara_analyzer:
  582. - Severity: HIGH
  583. - Threat Summary: Detected 2 threats: system access, command injection
  584. - Threat Names: SECURITY VIOLATION, SUSPICIOUS CODE EXECUTION
  585. - Total Findings: 2
  586. • llm_analyzer:
  587. - Severity: HIGH
  588. - Threat Summary: Detected 2 threats: prompt injection, tool poisoning
  589. - Threat Names: PROMPT INJECTION, SUSPICIOUS CODE EXECUTION
  590. - Total Findings: 2
  591. ```
  592. #### Table Format
  593. ```bash
  594. mcp-scanner --server-url http://127.0.0.1:8002/sse --format table
  595. ```
  596. ```
  597. === MCP Scanner Results Table ===
  598. Scan Target: http://127.0.0.1:8002/sse
  599. Scan Target Tool Name Status API YARA LLM Severity
  600. -----------------------------------------------------------------------------------------
  601. http://127.0.0.1:8002/sse exec_secrets UNSAFE HIGH HIGH HIGH HIGH
  602. http://127.0.0.1:8002/sse safe_command SAFE SAFE SAFE SAFE SAFE
  603. ```
  604. ## Documentation
  605. For detailed documentation, see the [docs/](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs) directory:
  606. - **[Architecture](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/architecture.md)** - System architecture and components
  607. - **[Behavioral Scanning](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/behavioral-scanning.md)** - Advanced static analysis with LLM-powered alignment checking
  608. - **[VirusTotal Scanning](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/virustotal-scanning.md)** - File and directory malware scanning with VirusTotal
  609. - **[PyPI Scanning](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/pypi-scanning.md)** - PyPI package scanning (Docker or local SDK mode)
  610. - **[npm Scanning](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/npm-scanning.md)** - npm package scanning with full JS/TS behavioral analysis (Docker or local SDK mode)
  611. - **[Vulnerable Package Scanning](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/vulnerable-package-scanning.md)** - Python dependency vulnerability scanning with pip-audit
  612. - **[LLM Providers](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/llm-providers.md)** - LLM configuration for all providers
  613. - **[MCP Threats Taxonomy](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/mcp-threats-taxonomy.md)** - Complete AITech threat taxonomy
  614. - **[Authentication](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/authentication.md)** - OAuth and security configuration
  615. - **[Programmatic Usage](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/programmatic-usage.md)** - Programmatic usage examples and advanced usage
  616. - **[Static Scanning](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/static-scanning.md)** - Offline/CI-CD scanning mode
  617. - **[API Reference](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/api-reference.md)** - Complete REST API documentation
  618. - **[Output Formats](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/output-formats.md)** - Detailed output format options
  619. ## Contact Cisco for obtaining an AI Defense subscription
  620. [https://www.cisco.com/c/en/us/products/security/ai-defense/request-demo.html](https://www.cisco.com/c/en/us/products/security/ai-defense/request-demo.html)
  621. ## License
  622. Distributed under the `Apache 2.0` License. See [LICENSE](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/LICENSE) for more information.
  623. Project Link: [https://github.com/cisco-ai-defense/mcp-scanner](https://github.com/cisco-ai-defense/mcp-scanner)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.