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.

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.

View on GitHub | PyPI Package | Join Discord

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
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
Static/Offline Scanning -- Scan pre-generated JSON files without live server connections, perfect for CI/CD pipelines and air-gapped environments
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
Customizable YARA Rules -- Add your own YARA rules to detect specific patterns

Installation

Prerequisites: Python 3.11+, uv (recommended), Cisco AI Defense API Key (optional), LLM Provider API Key (optional)

# Install as a CLI tool
uv tool install --python 3.13 cisco-ai-mcp-scanner

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

For local development:

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

As a dependency in other projects:

uv add cisco-ai-mcp-scanner

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

Quick Start

CLI Usage

# Scan well-known client configs on this machine
mcp-scanner --scan-known-configs --analyzers yara --format summary

# Stdio server
mcp-scanner --stdio-command uvx --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch --analyzers yara --format summary

# Remote server
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():
    config = Config(
        api_key="your_cisco_api_key",
        llm_provider_api_key="your_llm_api_key"
    )

    scanner = Scanner(config)

    tool_results = await scanner.scan_remote_server_tools(
        "https://mcp.deepwiki.com/mcp",
        analyzers=[AnalyzerEnum.API, AnalyzerEnum.YARA, AnalyzerEnum.LLM]
    )

    for result in tool_results:
        print(f"Tool: {result.tool_name}, Safe: {result.is_safe}")

asyncio.run(main())

Subcommands

Command	Description
remote	Scan a remote MCP server (SSE or streamable HTTP)
stdio	Launch and scan a stdio MCP server
config	Scan servers from a specific MCP config file
known-configs	Scan servers from well-known client config locations
prompts	Scan prompts on an MCP server
resources	Scan resources on an MCP server
instructions	Scan server instructions from InitializeResult
supplychain	Scan source code of an MCP server for behavioral analysis
static	Scan pre-generated MCP JSON files offline (CI/CD mode)

Scanning Examples

Scan Well-Known Configs

mcp-scanner --scan-known-configs --analyzers yara --format summary
mcp-scanner --scan-known-configs --analyzers yara --detailed

Scan a Stdio MCP Server

mcp-scanner --analyzers yara --format summary \
  stdio --stdio-command uvx \
  --stdio-arg=--from --stdio-arg=mcp-server-fetch --stdio-arg=mcp-server-fetch

Bearer Token with Remote Servers

mcp-scanner --analyzers yara --format summary \
  remote --server-url https://your-mcp-server/sse --bearer-token "$TOKEN"

Custom HTTP Headers

mcp-scanner --analyzers yara remote --server-url https://gateway.example.com/mcp \
  --header "Authorization: Bearer ingress-token" \
  --header "X-Egress-Auth: Bearer egress-token"

Scan Prompts

mcp-scanner --analyzers llm prompts --server-url http://127.0.0.1:8000/mcp
mcp-scanner --analyzers llm prompts --server-url http://127.0.0.1:8000/mcp --prompt-name "greet_user"

Scan Resources

mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp
mcp-scanner --analyzers llm resources --server-url http://127.0.0.1:8000/mcp \
  --resource-uri "file://test/document.txt"

Behavioral Code Scanning

mcp-scanner behavioral /path/to/mcp_server.py
mcp-scanner behavioral /path/to/mcp_servers/
mcp-scanner behavioral /path/to/mcp_server.py --format detailed

Static/Offline Files (CI/CD Mode)

mcp-scanner --analyzers yara static --tools /path/to/tools-list.json
mcp-scanner --analyzers yara,llm,api --format detailed static \
  --tools tools.json --prompts prompts.json --resources resources.json

Readiness Scanning

mcp-scanner --analyzers readiness --server-url http://localhost:8000/mcp
mcp-scanner --analyzers yara,readiness --server-url http://localhost:8000/mcp

API Server

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

Endpoints:

Endpoint	Description
`/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
`/scan-all-prompts`	Scan all prompts
`/scan-resource`	Scan a specific resource
`/scan-all-resources`	Scan all resources
`/scan-instructions`	Scan server instructions
`/health`	Health check

Output Formats

Format	Description
`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

Documentation

Guide	Description
Architecture	System architecture and components
Behavioral Scanning	Advanced static analysis with LLM-powered alignment checking
LLM Providers	LLM configuration for all providers
MCP Threats Taxonomy	Complete AITech threat taxonomy
Authentication	OAuth and security configuration
Programmatic Usage	Advanced programmatic usage examples
Static Scanning	Offline/CI-CD scanning mode
API Reference	Complete REST API documentation
Output Formats	Detailed output format options

License

Apache 2.0 -- See LICENSE for details.