mcp-scanner

The MCP Scanner is a Python-based toolset for scanning MCP servers, tools, prompts, and resources for security findings. It leverages three scanning engines (YARA, LLM-as-judge, and Cisco AI Defense) to provide flexible analyzers that can run together or independently. You can use the CLI to scan local MCP artifacts or run a REST API server for remote interactions, and you can also integrate the SDK into your Python projects to programmatically configure scanners and run analyses against MCP assets. Typical workflows include scanning local MCP configurations, scanning remote MCP servers, or performing static/offline analyses against pre-generated JSON artifacts.

Prerequisites:

• Python 3.11+
• uv (Python package manager) or pip for direct installation
• Optional: Cisco AI Defense API Key and LLM provider API keys depending on enabled analyzers

Option A: Install as a CLI tool via uv

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

Option B: Install from PyPI

python -m pip install cisco-ai-mcp-scanner

Option C: Install from source

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

Option D: Install as a dependency in other projects (example using uv)

uv init --python 3.13
uv add cisco-ai-mcp-scanner
# activate the virtual environment as appropriate for your platform
# then you can import mcpscanner in Python

Running the server locally (example):

# Run the MCP Scanner as a local Python module server (uses mcpscanner)
python -m mcpscanner

Note: For the UV-based workflow, you can also run the provided CLI commands to scan known configs, start a stdio server, or expose a REST API depending on how you configure the tool.

Environment variables commonly used with MCP Scanner:

• MCP_SCANNER_API_KEY: Cisco AI Defense API key (for API analyzer)
• MCP_SCANNER_ENDPOINT: Cisco AI Defense endpoint URL
• MCP_SCANNER_LLM_API_KEY: API key for LLM provider (e.g., OpenAI)
• MCP_SCANNER_LLM_MODEL, MCP_SCANNER_LLM_BASE_URL, MCP_SCANNER_LLM_API_VERSION: LLM configuration (optional)
• MCP_SCANNER_LLM_TIMEOUT: timeout in seconds for extended thinking models

Tips and common issues:

• Ensure Python 3.11+ is used and your PATH includes the Python and pip/uv executables.
• If using LLM-based analyzers, provide valid API keys and ensure network access to the LLM endpoint.
• When running as a REST API, specify host/port as needed (e.g., --host 0.0.0.0 --port 8080).
• If you encounter import errors after installation from source, verify that your virtual environment is activated and that mcpscanner is importable (pip list | grep mcpscanner).
• For offline/static scanning, prepare pre-generated MCP JSON artifacts and point the scanner to those files as supported by the SDK.