MCP Scanner

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-as-a-judge 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-as-judge, 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.
• 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.
• 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.
• 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)
• 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

Quick Start

Environment Setup

Core API Configuration

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

# 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.

# 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.

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:

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

# 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

# MCP Scanner as REST API
mcp-scanner-api --host 0.0.0.0 --port 8080

SDK Usage

import asyncio
from mcpscanner import Config, Scanner
from mcpscanner.core.models import AnalyzerEnum

async def main():
    # 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}")

# 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.
• config: scan servers from a specific MCP config file. Requires --config-path; optional --bearer-token.
• known-configs: scan servers from well-known client config locations on this machine; optional --bearer-token.
• 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 InitializeResult. 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).
• supplychain: scan source code of a MCP server for Behavioural analysis. requires 'path of MCP Server source code or MCP Server source file'
• supplychain: scan source code of an MCP server for Behavioural analysis. requires 'path of MCP Server source code or MCP Server source file'
• 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)

# 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

# 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

# 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

Use a Bearer token with remote servers (non-OAuth)

# 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)

# 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

# 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

# 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 in the MCP InitializeResult. Scanning instructions helps detect prompt injection, tool poisoning, and misleading guidance.

# 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.

# 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

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.

# Scan a single Python file
mcp-scanner behavioral /path/to/mcp_server.py

# Scan a directory
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 for complete technical details.

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.

# 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:

{
  "tools": [
    {
      "name": "tool_name",
      "description": "Tool description",
      "inputSchema": { "type": "object", "properties": {} }
    }
  ]
}

For more details, see Static Scanning Documentation and 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.

# 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 for complete technical details.

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.

# 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 InitializeResult
• /health - Health check endpoint

Documentation is available in 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

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

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/ directory:

• Architecture - System architecture and components
• Behavioral Scanning - Advanced static analysis with LLM-powered alignment checking
• VirusTotal Scanning - File and directory malware scanning with VirusTotal
• LLM Providers - LLM configuration for all providers
• MCP Threats Taxonomy - Complete AITech threat taxonomy
• Authentication - OAuth and security configuration
• Programmatic Usage - Programmatic usage examples and advanced usage
• Static Scanning - Offline/CI-CD scanning mode
• API Reference - Complete REST API documentation
• Output Formats - 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

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

Project Link: https://github.com/cisco-ai-defense/mcp-scanner