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.
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
Markdown
[](/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
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.
- # MCP Scanner
- [](https://opensource.org/licenses/Apache-2.0)
- [](https://www.python.org/downloads/)
- [](https://pypi.org/project/cisco-ai-mcp-scanner/)
- [](https://discord.com/invite/nKWtDcXxtx)
- [](https://www.cisco.com/site/us/en/products/security/ai-defense/index.html)
- [](https://learn-cloudsecurity.cisco.com/ai-security-framework)
- 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.
- ## Overview
- 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.
- The SDK is designed to be easy to use while providing powerful scanning capabilities, flexible authentication options, and customization.
- 
- ## Features
- - **Multiple Modes:** Run scanner as a stand-alone CLI tool or REST API server
- - **Multi-Engine Security Analysis**: Use all three scanning engines together or independently based on your needs.
- - **Vulnerable Packages Scanning**: Scan Python dependencies for known vulnerabilities (CVE/PYSEC/GHSA) using pip-audit integration.
- - **Readiness Scanning**: Zero-dependency static analysis for production readiness issues (timeouts, retries, error handling).
- - **Comprehensive Scanning**: Scan MCP tools, prompts, resources, and server instructions for security findings
- - **Behavioural Code Scanning**: Scan Source code of MCP servers for finding threats.
- - **VirusTotal Binary Scanning**: Automatically detect malware in binary files (images, PDFs, executables, archives) bundled with MCP servers using VirusTotal hash lookups.
- - **PyPI Package Scanning**: Download and scan PyPI packages inside a Docker sandbox with behavioral analysis.
- - **Behavioural Code Scanning**: Scan Source code of MCP servers for detecting threats.
- - **Static/Offline Scanning**: Scan pre-generated JSON files without live server connections - perfect for CI/CD pipelines and air-gapped environments
- - **Explicit Authentication Control**: Fine-grained control over authentication with explicit Auth parameters.
- - **OAuth Support**: Full OAuth authentication support for both SSE and streamable HTTP connections.
- - **Custom Endpoints**: Configure the API endpoint to support any Cisco AI Defense environments.
- - **MCP Server Integration**: Connect directly to MCP servers to scan tools, prompts, and resources with flexible authentication.
- - **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.
- - **Customizable YARA Rules**: Add your own YARA rules to detect specific patterns.
- - **Comprehensive Reporting**: Detailed reports on detected security findings.
- ## Installation
- ### Prerequisites
- - Python 3.11+
- - uv (Python package manager)
- - **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.
- - 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
- ```bash
- uv tool install --python 3.13 cisco-ai-mcp-scanner
- ```
- Alternatively, you can install from source:
- ```bash
- uv tool install --python 3.13 --from git+https://github.com/cisco-ai-defense/mcp-scanner cisco-ai-mcp-scanner
- ```
- ### Installing for local development
- ```bash
- git clone https://github.com/cisco-ai-defense/mcp-scanner
- cd mcp-scanner
- uv sync --python 3.13
- ```
- ### MCP protocol compatibility
- Live scans (remote HTTP/SSE and stdio) negotiate the MCP protocol version automatically:
- 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`**.
- 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`).
- 3. **Backward compatible:** Existing stdio and remote servers that predate mcp 2.0 continue to work without changes on the scanner side.
- The Python MCP 1.x stdio server reports an unknown `server/discover` request as
- a generic `-32602` invalid-parameters error. The scanner retries `initialize()`
- for that specific stdio error shape and logs a warning. Other `-32602` errors
- surface to the caller so malformed modern discovery is not silently downgraded.
- 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.
- Integration tests: `uv run pytest tests/test_stdio_modern_integration.py tests/test_scanner.py -k negotiate`
- For an unauthenticated HTTP endpoint, run read-only wire-protocol probes with
- `mcp-scanner protocol --server-url https://your-server.example/mcp`. This checks
- modern request envelope headers on servers advertising `2026-07-28` and runs
- safe legacy checks for older endpoints. It does not call tools or prove
- that unauthenticated callers can invoke them. A protected endpoint may require
- separate authorized testing to assess its behavior after authentication.
- The opt-in `schema` analyzer classifies nested `$ref` values in advertised
- tool input and output schemas. Use `--analyzers schema` to run this check,
- including with the `static --tools` mode. See
- [MCP 2.0 threat coverage](docs/mcp-2-threat-coverage.md)
- for the scan-time and runtime boundary.
- ### Install as a dependency in other projects
- Add MCP Scanner as a dependency using uv. From your project root (initialize with uv if needed):
- ```bash
- 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:
- ```python
- # import everything (not recommended)
- import mcpscanner
- # selective imports (recommended). For example:
- from mcpscanner import Config, Scanner
- from mcpscanner.core.models import AnalyzerEnum
- ```
- ## Quick Start
- ### Environment Setup
- #### Core API Configuration
- ```bash
- Cisco AI Defense API (only required for API analyzer)
- export MCP_SCANNER_API_KEY="your_cisco_api_key"
- export MCP_SCANNER_ENDPOINT="https://us.api.inspect.aidefense.security.cisco.com/api/v1"
- # For other endpoints please visit https://developer.cisco.com/docs/ai-defense/getting-started/#base-url
- ```
- #### LLM Configuration (for LLM analyzer and Code Behavioral Analyzer)
- **Tested LLMs:** OpenAI GPT-4o and GPT-4.1 | AWS Bedrock Claude 4.5 Sonnet
- ```bash
- # AWS Bedrock Claude with AWS credentials (profile)
- export AWS_PROFILE="your-profile"
- export AWS_REGION="us-east-1"
- export MCP_SCANNER_LLM_MODEL="bedrock/anthropic.claude-sonnet-4-5-20250929-v2:0" # Any AWS Bedrock supported model
- # AWS Bedrock Claude with API key (Bearer token)
- export MCP_SCANNER_LLM_API_KEY="bedrock-api-key-..." # Generated via Amazon Bedrock -> API Keys
- export AWS_REGION="us-east-1"
- export MCP_SCANNER_LLM_MODEL="bedrock/us.anthropic.claude-sonnet-4-5-20250929-v2:0" # Any AWS Bedrock supported model
- # LLM Provider API Key (required for LLM analyzer)
- export MCP_SCANNER_LLM_API_KEY="your_llm_api_key" # OpenAI
- # LLM Model Configuration (optional - defaults provided)
- export MCP_SCANNER_LLM_MODEL="gpt-5.2" # Any LiteLLM-supported model
- export MCP_SCANNER_LLM_BASE_URL="https://api.openai.com/v1" # Custom LLM endpoint
- export MCP_SCANNER_LLM_API_VERSION="2025-04-01-preview" # API version (if required)
- # For Azure OpenAI (example)
- export MCP_SCANNER_LLM_BASE_URL="https://your-resource.openai.azure.com/"
- export MCP_SCANNER_LLM_API_VERSION="2025-04-01-preview"
- export MCP_SCANNER_LLM_MODEL="azure/gpt-5.2"
- # For Extended Thinking Models (longer timeout)
- export MCP_SCANNER_LLM_TIMEOUT=300
- ```
- 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.
- #### VirusTotal Configuration (for file/directory malware scanning)
- 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`.
- ```bash
- # VirusTotal API key (get one free at https://www.virustotal.com/)
- export VIRUSTOTAL_API_KEY="your_virustotal_api_key"
- # Optional: explicitly disable VirusTotal scanning even when API key is present.
- # When not set, scanning is auto-enabled if VIRUSTOTAL_API_KEY is configured.
- # Set to "false" to skip VT scanning without removing the API key (e.g. in CI).
- export MCP_SCANNER_VIRUSTOTAL_ENABLED=false
- # Optional: Upload unknown files to VirusTotal for scanning (default: false, privacy-friendly)
- export MCP_SCANNER_VIRUSTOTAL_UPLOAD_FILES=false
- # Optional: Max files to scan per directory (default: 10, set to 0 for unlimited)
- export MCP_SCANNER_VT_MAX_FILES=10
- ```
- > **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.
- #### Stdio Connection Timeout
- 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`.
- ```bash
- # Increase stdio server startup timeout (default: 60 seconds)
- export MCP_SCANNER_STDIO_TIMEOUT=180 # 3 minutes — useful for servers with heavy deps
- # Or use the CLI flag (overrides the environment variable)
- mcp-scanner --stdio-timeout 180 stdio --stdio-command uvx --stdio-arg mcp-clickhouse
- ```
- #### Using a Local LLM (No API Key Required)
- If you are using a local LLM endpoint such as Ollama, vLLM, or LocalAI,
- the `MCP_SCANNER_LLM_API_KEY` variable is still required but can be set to any value.
- Example:
- ```bash
- export MCP_SCANNER_LLM_API_KEY=test
- export MCP_SCANNER_LLM_ENDPOINT=http://localhost:11434
- ```
- ### Quick Start Examples
- 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.
- #### CLI Usage
- ```bash
- # Scan well-known client configs on this machine
- mcp-scanner --scan-known-configs --analyzers yara --format summary
- # Stdio server (example using uvx mcp-server-fetch)
- mcp-scanner --stdio-command uvx --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch --analyzers yara --format summary
- # Remote server (deepwiki example)
- mcp-scanner --server-url https://mcp.deepwiki.com/mcp --analyzers yara --format summary
- # Suppress all output below ERROR (useful in CI/CD)
- mcp-scanner --log-level error --analyzers yara --format raw --server-url https://mcp.deepwiki.com/mcp
- # MCP Scanner as REST API
- mcp-scanner-api --host 0.0.0.0 --port 8080
- ```
- #### SDK Usage
- ```python
- import asyncio
- import os
- from mcpscanner import Config, Scanner, set_log_level
- from mcpscanner.core.models import AnalyzerEnum
- import logging
- async def main():
- # Suppress all mcpscanner logs below ERROR
- set_log_level(logging.ERROR)
- # Create configuration with your API keys
- config = Config(
- api_key="your_cisco_api_key",
- llm_provider_api_key="your_llm_api_key"
- )
- # Create scanner
- scanner = Scanner(config)
- # Scan all tools on a remote server
- tool_results = await scanner.scan_remote_server_tools(
- "https://mcp.deepwiki.com/mcp",
- analyzers=[AnalyzerEnum.API, AnalyzerEnum.YARA, AnalyzerEnum.LLM]
- )
- # Print tool results
- for result in tool_results:
- print(f"Tool: {result.tool_name}, Safe: {result.is_safe}")
- # Scan all prompts on a server
- prompt_results = await scanner.scan_remote_server_prompts(
- "http://127.0.0.1:8000/mcp",
- analyzers=[AnalyzerEnum.LLM]
- )
- # Print prompt results
- for result in prompt_results:
- print(f"Prompt: {result.prompt_name}, Safe: {result.is_safe}")
- # Scan all resources on a server
- resource_results = await scanner.scan_remote_server_resources(
- "http://127.0.0.1:8000/mcp",
- analyzers=[AnalyzerEnum.LLM],
- allowed_mime_types=["text/plain", "text/html"]
- )
- # Print resource results
- for result in resource_results:
- print(f"Resource: {result.resource_name}, Safe: {result.is_safe}, Status: {result.status}")
- # Scan a stdio server while suppressing its stderr output
- from mcpscanner.core.mcp_models import StdioServer
- server = StdioServer(command="uvx", args=["mcp-server-fetch"])
- with open(os.devnull, "w") as devnull:
- stdio_results = await scanner.scan_stdio_server_tools(
- server,
- analyzers=[AnalyzerEnum.YARA],
- errlog=devnull
- )
- # Run the scanner
- asyncio.run(main())
- ```
- #### Subcommands Overview
- - **remote**: scan a remote MCP server (SSE or streamable HTTP). Supports `--server-url`, optional `--bearer-token`, `--header`.
- - **stdio**: launch and scan a stdio MCP server. Requires `--stdio-command`; accepts `--stdio-args`, `--stdio-env`, optional `--stdio-tool`, `--stdio-timeout`.
- - **config**: scan servers from a specific MCP config file. Requires `--config-path`; optional `--bearer-token`, `--stderr-file`.
- - **known-configs**: scan servers from well-known client config locations on this machine; optional `--bearer-token`, `--stderr-file`.
- - **prompts**: scan prompts on an MCP server. Requires `--server-url`; optional `--prompt-name`, `--bearer-token`, `--header`.
- - **resources**: scan resources on an MCP server. Requires `--server-url`; optional `--resource-uri`, `--mime-types`, `--bearer-token`, `--header`.
- - **instructions**: scan server instructions from the connect handshake (`DiscoverResult` on mcp 2.0, `InitializeResult` on legacy servers). Requires `--server-url`; optional `--bearer-token`.
- - **virustotal**: scan files or directories for malware using VirusTotal hash lookups. Requires a `scan_path` argument (file or directory).
- - **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.
- - **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.
- - **supplychain**: scan source code of an MCP server for Behavioural analysis. Requires path to MCP Server source code or source file.
- - **vulnerable-package**: scan Python dependencies for known vulnerabilities using pip-audit. Requires a path to a requirements file or project directory.
- - **static**: scan pre-generated MCP JSON files offline (CI/CD mode). Supports `--tools`, `--prompts`, `--resources`, optional `--mime-types`.
- 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.
- #### Additional Examples
- #### Scan well-known MCP config paths (Windsurf, Cursor, Claude, VS Code)
- ```bash
- # YARA-only scan of all servers defined in well-known config locations
- mcp-scanner --scan-known-configs --analyzers yara --format summary
- # Detailed output
- mcp-scanner --scan-known-configs --analyzers yara --detailed
- ```
- #### Scan a specific MCP config file
- ```bash
- # Expand ~ yourself if needed by your shell
- mcp-scanner --config-path "$HOME/.codeium/windsurf/mcp_config.json" \
- --analyzers yara --format by_tool
- ```
- #### Scan a stdio MCP server
- ```bash
- # Use repeated --stdio-arg for reliable argument passing
- mcp-scanner --analyzers yara --format summary \
- stdio --stdio-command uvx \
- --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch
- # Or list-form (ensure it doesn't conflict with later flags)
- mcp-scanner --analyzers yara --detailed \
- stdio --stdio-command uvx \
- --stdio-args --from mcp-server-fetch mcp-server-fetch
- # Scan only a specific tool on the stdio server
- mcp-scanner --analyzers yara --format summary \
- stdio --stdio-command uvx \
- --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch \
- --stdio-tool fetch
- # Increase startup timeout for servers with heavy dependencies (default: 60s)
- mcp-scanner --stdio-timeout 180 --analyzers yara --format summary \
- stdio --stdio-command uvx --stdio-arg mcp-clickhouse@0.1.13
- ```
- #### Use a Bearer token with remote servers (non-OAuth)
- ```bash
- # Direct remote server with Bearer token
- mcp-scanner --analyzers yara --format summary \
- remote --server-url https://your-mcp-server/sse --bearer-token "$TOKEN"
- # Apply Bearer token to all remote servers discovered from configs
- mcp-scanner --analyzers yara --detailed known-configs --bearer-token "$TOKEN"
- mcp-scanner --analyzers yara --format by_tool \
- config --config-path "$HOME/.codeium/windsurf/mcp_config.json" --bearer-token "$TOKEN"
- ```
- #### Use custom HTTP headers (e.g., MCP Gateway dual-token auth)
- ```bash
- # Single custom header
- mcp-scanner --analyzers yara remote --server-url https://your-mcp-server/mcp \
- --header "X-API-Key: your-api-key"
- # Multiple custom headers (MCP Gateway dual-token authentication)
- mcp-scanner --analyzers yara remote --server-url https://gateway.example.com/mcp \
- --header "Authorization: Bearer ingress-token" \
- --header "X-Egress-Auth: Bearer egress-token"
- ```
- > **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).
- #### Scan Prompts
- ```bash
- # Scan all prompts on an MCP server
- mcp-scanner --analyzers llm prompts --server-url http://127.0.0.1:8000/mcp
- # Scan all prompts with detailed output
- mcp-scanner --analyzers llm --detailed prompts --server-url http://127.0.0.1:8000/mcp
- # Scan all prompts with table format
- mcp-scanner --analyzers llm --format table prompts --server-url http://127.0.0.1:8000/mcp
- # Scan a specific prompt by name
- mcp-scanner --analyzers llm prompts --server-url http://127.0.0.1:8000/mcp --prompt-name "greet_user"
- # Get raw JSON output
- mcp-scanner --analyzers llm --raw prompts --server-url http://127.0.0.1:8000/mcp
- ```
- #### Scan Resources
- ```bash
- # Scan all resources on an MCP server
- mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp
- # Scan all resources with detailed output
- mcp-scanner --analyzers llm --detailed resources --server-url http://127.0.0.1:8000/mcp
- # Scan all resources with table format
- mcp-scanner --analyzers llm --format table resources --server-url http://127.0.0.1:8000/mcp
- # Scan a specific resource by URI
- mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp \
- --resource-uri "file://test/document.txt"
- # Scan with custom MIME type filtering
- mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp \
- --mime-types "text/plain,text/html,application/json"
- ```
- #### Scan Server Instructions
- 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.
- ```bash
- # Scan server instructions (defaults to API, YARA, and LLM analyzers)
- mcp-scanner instructions --server-url http://127.0.0.1:8000/mcp
- # Scan with detailed output
- mcp-scanner --detailed instructions --server-url http://127.0.0.1:8000/mcp
- # Scan with specific analyzers (LLM recommended for semantic analysis)
- mcp-scanner --analyzers llm instructions --server-url http://127.0.0.1:8000/mcp
- # Get raw JSON output
- mcp-scanner --raw instructions --server-url http://127.0.0.1:8000/mcp
- # With authentication
- mcp-scanner instructions --server-url https://your-server.com/mcp --bearer-token "$TOKEN"
- ```
- #### VirusTotal Malware Scanning
- 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.
- ```bash
- # Scan a single file
- mcp-scanner virustotal /path/to/suspicious_file.exe
- # Scan a directory
- mcp-scanner virustotal /path/to/mcp_server_package/
- # With detailed output
- mcp-scanner virustotal /path/to/mcp_server_package/ --format detailed
- # Table format
- mcp-scanner virustotal /path/to/mcp_server_package/ --format table
- # Save results to file
- mcp-scanner virustotal /path/to/file.bin --output vt_results.json --format raw
- ```
- > **Note:** Requires `VIRUSTOTAL_API_KEY` environment variable. Free tier allows 4 requests/minute and 500 requests/day.
- #### Behavioral Code Scanning (Multi-Language)
- 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.
- **Supported Languages:** Python, TypeScript, JavaScript, Go, Java, Kotlin, C#, Rust, Ruby, PHP
- ```bash
- # Scan a single file (any supported language)
- mcp-scanner behavioral /path/to/mcp_server.py
- mcp-scanner behavioral /path/to/server.ts
- mcp-scanner behavioral /path/to/server.go
- mcp-scanner behavioral /path/to/McpService.java
- mcp-scanner behavioral /path/to/server.kt
- mcp-scanner behavioral /path/to/Tools.cs
- mcp-scanner behavioral /path/to/server.rs
- # Scan a directory (auto-detects language by extension)
- mcp-scanner behavioral /path/to/mcp_servers/
- # With specific output format
- mcp-scanner behavioral /path/to/mcp_server.py --format by_severity
- # Detailed analysis with all findings
- mcp-scanner behavioral /path/to/mcp_server.py --format detailed
- # Save results to file
- mcp-scanner behavioral /path/to/mcp_server.py --output results.json --format raw
- ```
- See [Behavioral Scanning Documentation](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/behavioral-scanning.md) for complete technical details.
- #### PyPI Package Scanning
- 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.
- ```bash
- # Scan a package (latest version)
- mcp-scanner pypi-scan flask
- # Scan a specific version
- mcp-scanner pypi-scan requests --version 2.31.0
- # Save results
- mcp-scanner pypi-scan fastapi -o results.json --format detailed
- # Force rebuild the Docker image
- mcp-scanner pypi-scan flask --rebuild-image
- ```
- See [PyPI Scanning Documentation](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/pypi-scanning.md) for complete details.
- #### Scan an npm Package
- ```bash
- # Scan latest version (Docker-sandboxed)
- mcp-scanner npm-scan @modelcontextprotocol/server-everything
- # Specific version
- mcp-scanner npm-scan my-mcp-server --version 1.2.3
- # No-Docker SDK / CI runner mode
- mcp-scanner npm-scan my-mcp-server --no-docker
- ```
- See [npm Scanning Documentation](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/npm-scanning.md) for complete details.
- #### Vulnerable Packages Scanning
- 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.
- ```bash
- # Scan a requirements file
- mcp-scanner vulnerable-package /path/to/requirements.txt
- # Scan a project directory (auto-detects requirements.txt or pyproject.toml)
- mcp-scanner vulnerable-package /path/to/project/
- # Use OSV vulnerability service instead of PyPI
- mcp-scanner vulnerable-package /path/to/requirements.txt --vulnerability-service osv
- # Detailed output with full vulnerability descriptions
- mcp-scanner vulnerable-package /path/to/requirements.txt --format detailed
- # Save results to file
- mcp-scanner vulnerable-package /path/to/requirements.txt --output results.json --format raw
- # Automatically fix vulnerable dependencies
- mcp-scanner vulnerable-package /path/to/requirements.txt --fix
- ```
- Each vulnerability is mapped to the Cisco AI Threat Security Taxonomy under **AITech-9.3 / AISubtech-9.3.1 (Malicious Package / Tool Injection)**.
- #### Scan Static/Offline Files (CI/CD Mode)
- 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.
- ```bash
- # Scan tools from a static JSON file
- mcp-scanner --analyzers yara static --tools /path/to/tools-list.json
- # Scan with multiple analyzers
- mcp-scanner --analyzers yara,llm static --tools /path/to/tools-list.json
- # Scan prompts from a static JSON file
- mcp-scanner --analyzers llm static --prompts /path/to/prompts-list.json
- # Scan resources from a static JSON file
- mcp-scanner --analyzers llm static --resources /path/to/resources-list.json
- # Scan all three types at once with detailed output
- mcp-scanner \
- --analyzers yara,llm,api \
- --format detailed \
- static \
- --tools /path/to/tools-list.json \
- --prompts /path/to/prompts-list.json \
- --resources /path/to/resources-list.json
- # CI/CD example: YARA-only scan (no API keys needed)
- mcp-scanner --analyzers yara --format summary static --tools output/tools.json
- ```
- **Expected JSON Format:**
- ```json
- {
- "tools": [
- {
- "name": "tool_name",
- "description": "Tool description",
- "inputSchema": { "type": "object", "properties": {} }
- }
- ]
- }
- ```
- For resources, static scanning accepts either `resources/list` metadata or a
- `resources/read` content snapshot:
- ```json
- {
- "contents": [
- {
- "uri": "file:///path/to/document.txt",
- "mimeType": "text/plain",
- "text": "Resource contents to scan"
- }
- ]
- }
- ```
- For more details, see [Static Scanning Documentation](docs/static-scanning.md) and [examples/static_scanning_example.py](examples/static_scanning_example.py).
- #### Readiness Scanning
- 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.
- ```bash
- # Readiness-only scan (no API keys required)
- mcp-scanner --analyzers readiness --server-url http://localhost:8000/mcp
- # Combined security + readiness scan
- mcp-scanner --analyzers yara,readiness --server-url http://localhost:8000/mcp
- # Detailed readiness output
- mcp-scanner --analyzers readiness --detailed --server-url http://localhost:8000/mcp
- ```
- See [Readiness Scanning Documentation](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/readiness-scanning.md) for complete technical details.
- ### Prompt Defense Scanning
- 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.
- **Attack vectors checked:**
- 1. Instruction Override (HIGH)
- 2. Data Leakage (HIGH)
- 3. Role Escape (HIGH)
- 4. Indirect Injection (HIGH)
- 5. Output Weaponization (HIGH)
- 6. Output Manipulation (MEDIUM)
- 7. Multilingual Bypass (MEDIUM)
- 8. Unicode/Homoglyph Attack (MEDIUM)
- 9. Context Overflow (MEDIUM)
- 10. Social Engineering (MEDIUM)
- 11. Input Validation (MEDIUM)
- 12. Abuse Prevention (LOW)
- ```bash
- # Prompt defense scan only (no API keys required)
- mcp-scanner --analyzers prompt_defense --server-url http://localhost:8000/mcp
- # Combined security + prompt defense scan
- mcp-scanner --analyzers yara,prompt_defense --server-url http://localhost:8000/mcp
- ```
- Each missing defense maps to MCP Taxonomy codes (AITech / AISubtech) for standardized reporting.
- ### Logging Control
- By default the CLI shows `WARNING`-level output (or `DEBUG` with `--verbose`). For finer control use `--log-level`:
- ```bash
- # Show only errors (good for CI/CD)
- mcp-scanner --log-level error --analyzers yara --format raw --server-url https://mcp.deepwiki.com/mcp
- # Show warnings and above
- mcp-scanner --log-level warning --analyzers yara --format summary --scan-known-configs
- # Full debug output (equivalent to --verbose)
- mcp-scanner --log-level debug --analyzers yara --server-url https://mcp.deepwiki.com/mcp
- ```
- `--log-level` takes precedence over `--verbose` when both are provided.
- #### Library Log Level (SDK)
- Library consumers can control the log level programmatically. Unlike
- `logging.getLogger("mcpscanner").setLevel(...)`, which does not propagate
- to child loggers, `set_log_level` updates **every** mcpscanner logger and
- handler:
- ```python
- import logging
- from mcpscanner import set_log_level
- set_log_level(logging.ERROR) # suppress everything below ERROR
- set_log_level(logging.DEBUG) # show all debug output
- ```
- #### Suppressing Stdio Server Stderr
- MCP servers launched via stdio may emit noisy output to stderr (startup
- banners, dependency logs, etc.). All stdio scan methods accept an `errlog`
- parameter to redirect or suppress this output:
- ```python
- import os
- from mcpscanner import Scanner, Config
- from mcpscanner.core.mcp_models import StdioServer
- scanner = Scanner(Config())
- server = StdioServer(command="uvx", args=["mcp-server-fetch"])
- with open(os.devnull, "w") as devnull:
- results = await scanner.scan_stdio_server_tools(server, errlog=devnull)
- prompts = await scanner.scan_stdio_server_prompts(server, errlog=devnull)
- ```
- The `errlog` parameter is supported on `scan_stdio_server_tools`,
- `scan_stdio_server_tool`, `scan_stdio_server_prompts`,
- `scan_stdio_server_prompt`, `scan_well_known_mcp_configs`, and
- `scan_mcp_config_file`.
- ### API Server Usage
- 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.
- ```bash
- # Start the API server (loads configuration from .env file)
- mcp-scanner-api --port 8000
- # Or with custom host and port
- mcp-scanner-api --host 0.0.0.0 --port 8080
- # Enable development mode with auto-reload
- mcp-scanner-api --reload
- ```
- Once running, the API server provides endpoints for:
- - **`/scan-tool`** - Scan a specific tool on an MCP server
- - **`/scan-all-tools`** - Scan all tools on an MCP server
- - **`/scan-prompt`** - Scan a specific prompt on an MCP server
- - **`/scan-all-prompts`** - Scan all prompts on an MCP server
- - **`/scan-resource`** - Scan a specific resource on an MCP server
- - **`/scan-all-resources`** - Scan all resources on an MCP server
- - **`/scan-instructions`** - Scan server instructions from the MCP connect handshake
- - **`/health`** - Health check endpoint
- 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.
- ## Output Formats
- The scanner supports multiple output formats:
- - **`summary`**: Concise overview with key findings
- - **`detailed`**: Comprehensive analysis with full findings breakdown
- - **`table`**: Clean tabular format
- - **`by_severity`**: Results grouped by severity level
- - **`raw`**: Raw JSON output
- ### Example Output
- #### Detailed Format
- ```bash
- mcp-scanner --server-url http://127.0.0.1:8001/sse --format detailed
- ```
- ```
- === MCP Scanner Detailed Results ===
- Scan Target: http://127.0.0.1:8001/sse
- Tool: execute_system_command
- Status: completed
- Safe: No
- Analyzer Results:
- • api_analyzer:
- - Severity: HIGH
- - Threat Summary: Detected 1 threat: security violation
- - Threat Names: SECURITY VIOLATION
- - Total Findings: 1
- • yara_analyzer:
- - Severity: HIGH
- - Threat Summary: Detected 2 threats: system access, command injection
- - Threat Names: SECURITY VIOLATION, SUSPICIOUS CODE EXECUTION
- - Total Findings: 2
- • llm_analyzer:
- - Severity: HIGH
- - Threat Summary: Detected 2 threats: prompt injection, tool poisoning
- - Threat Names: PROMPT INJECTION, SUSPICIOUS CODE EXECUTION
- - Total Findings: 2
- ```
- #### Table Format
- ```bash
- mcp-scanner --server-url http://127.0.0.1:8002/sse --format table
- ```
- ```
- === MCP Scanner Results Table ===
- Scan Target: http://127.0.0.1:8002/sse
- Scan Target Tool Name Status API YARA LLM Severity
- -----------------------------------------------------------------------------------------
- http://127.0.0.1:8002/sse exec_secrets UNSAFE HIGH HIGH HIGH HIGH
- http://127.0.0.1:8002/sse safe_command SAFE SAFE SAFE SAFE SAFE
- ```
- ## Documentation
- For detailed documentation, see the [docs/](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs) directory:
- - **[Architecture](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/architecture.md)** - System architecture and components
- - **[Behavioral Scanning](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/behavioral-scanning.md)** - Advanced static analysis with LLM-powered alignment checking
- - **[VirusTotal Scanning](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/virustotal-scanning.md)** - File and directory malware scanning with VirusTotal
- - **[PyPI Scanning](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/pypi-scanning.md)** - PyPI package scanning (Docker or local SDK mode)
- - **[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)
- - **[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
- - **[LLM Providers](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/llm-providers.md)** - LLM configuration for all providers
- - **[MCP Threats Taxonomy](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/mcp-threats-taxonomy.md)** - Complete AITech threat taxonomy
- - **[Authentication](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/authentication.md)** - OAuth and security configuration
- - **[Programmatic Usage](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/programmatic-usage.md)** - Programmatic usage examples and advanced usage
- - **[Static Scanning](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/static-scanning.md)** - Offline/CI-CD scanning mode
- - **[API Reference](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/api-reference.md)** - Complete REST API documentation
- - **[Output Formats](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/docs/output-formats.md)** - Detailed output format options
- ## Contact Cisco for obtaining an AI Defense subscription
- [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)
- ## License
- Distributed under the `Apache 2.0` License. See [LICENSE](https://github.com/cisco-ai-defense/mcp-scanner/tree/main/LICENSE) for more information.
- 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 inFree to use. If it’s helped, pass it on.