MCP Security Analyzer

A comprehensive security testing framework for analyzing Model Context Protocol (MCP) server implementations. Automatically executes MCP servers in isolated Docker containers while capturing and analyzing network traffic to detect security vulnerabilities including data exfiltration, unauthorized access, command injection, and privilege escalation.

🎯 Overview

MCP Security Analyzer helps security teams and developers validate the security posture of MCP server implementations by:

Automated Testing: Run predefined security test scenarios against any MCP server
Network Monitoring: Capture and analyze all network traffic during execution
Threat Detection: Identify suspicious patterns, sensitive data exposure, and unauthorized access
AI-Powered Analysis: Optional Claude API integration for intelligent threat assessment
Comprehensive Reports: Generate detailed security reports in HTML, JSON, and CSV formats

✨ Key Features

🔒 Security Testing

Pre-configured security use cases (file access, data exfiltration, command injection, privilege escalation)
MCP protocol method testing (tools/call, resources/list, prompts/list)
Sensitive data pattern detection (credentials, API keys, PII)
Path traversal and command injection detection

🐳 Docker Isolation

Sandboxed execution environment with resource limits
Network isolation and monitoring
Automatic cleanup of containers and resources

📊 Analysis & Reporting

Deep packet inspection with Scapy
Connection analysis and payload inspection
Claude AI-powered threat assessment (optional)
Multi-format reporting (HTML, JSON, CSV)

🚀 Simple Usage

No complex tool definitions required
Pass MCP server command directly
Choose from predefined security test scenarios
Get actionable security reports

📋 Requirements

System Requirements

Python: 3.9 or higher
Docker: Docker Engine running (tested with Docker 20.10+)
Network: Packet capture capabilities (libpcap on Linux/macOS, WinPcap/Npcap on Windows)
Resources: Minimum 4GB RAM, 10GB disk space

Platform Support

✅ Linux: Ubuntu 20.04+, RHEL 8+, CentOS 8+, Debian 11+
✅ macOS: 10.15 (Catalina) or higher
✅ Windows: Windows 10+ with WSL2 (recommended) or native with limitations

🚀 Installation

1. Install System Dependencies

Ubuntu/Debian

sudo apt-get update
sudo apt-get install -y python3 python3-pip docker.io libpcap-dev tcpdump
sudo systemctl start docker
sudo usermod -aG docker $USER

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install python@3.9
brew install libpcap
brew install --cask docker

# Start Docker Desktop
open -a Docker

Windows (WSL2)

# Install WSL2 and Ubuntu
wsl --install

# Inside WSL2, follow Ubuntu instructions above

2. Install MCP Security Analyzer

From Source (Recommended)

# Clone the repository
git clone https://github.com/yair4data/mcp-security-analyzer.git
cd mcp-security-analyzer

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

Verify Installation

# Check Docker is running
docker version

# Verify analyzer installation
mcp-security-analyzer --version

3. Optional: Configure Claude AI

For AI-powered threat analysis:

export CLAUDE_API_KEY="your-anthropic-api-key"
# Or add to ~/.bashrc or ~/.zshrc for persistence

Get your API key from: https://console.anthropic.com/

📖 Usage

Quick Start (30 seconds)

# 1. Copy example configuration
cp config/simple-usecases.yaml config/my-config.yaml

# 2. Run security inspection
mcp-security-analyzer --config config/my-config.yaml inspect \
    "npx -y @modelcontextprotocol/server-filesystem /tmp" \
    --use-case basic_security_scan

# 3. View report
open ./mcp_analysis/security_report.html

Basic Commands

Inspect MCP Server

Test any MCP server with predefined security scenarios:

# Run specific security test
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-filesystem /tmp" \
    --use-case sensitive_file_access

# Run all available security tests
mcp-security-analyzer inspect \
    "python my_mcp_server.py"

# Custom output directory
mcp-security-analyzer inspect \
    "node mcp-server.js" \
    --use-case data_exfiltration \
    --output ./security_reports

With AI Analysis

export CLAUDE_API_KEY="your-key"

mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-brave-search" \
    --use-case basic_security_scan

Disable AI Analysis

mcp-security-analyzer inspect \
    "python server.py" \
    --use-case command_injection \
    --no-ai

Available Security Use Cases

The tool includes 5 pre-configured security test scenarios:

Use Case	Description	Test Actions	Duration
`basic_security_scan`	Overview of server capabilities	3	~2 min
`sensitive_file_access`	File permission testing	3	~3 min
`data_exfiltration`	Data theft scenarios	2	~3 min
`command_injection`	Injection vulnerability testing	2	~2 min
`privilege_escalation`	Privilege escalation attempts	2	~2 min

Example: Testing Official MCP Servers

# Test filesystem server
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-filesystem /tmp" \
    --use-case sensitive_file_access

# Test GitHub server
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-github" \
    --use-case basic_security_scan

# Test Brave Search server
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-brave-search" \
    --use-case data_exfiltration

Example: Testing Custom Python MCP Server

mcp-security-analyzer inspect \
    "python /path/to/my_mcp_server.py" \
    --use-case basic_security_scan \
    --output ./my_server_analysis

📊 Understanding Reports

After running an analysis, you'll find:

mcp_analysis/
├── security_report.html    # Interactive HTML report (open in browser)
├── security_report.json    # Machine-readable JSON data
├── findings.csv            # Tabular security findings
└── mcp_traffic.pcap        # Network traffic capture (for deep analysis)

Report Sections

HTML Report includes:

✅ Executive Summary
✅ Inspector Execution Results
✅ Network Traffic Analysis
✅ Security Findings by Severity (Critical/High/Medium/Low)
✅ AI-Powered Threat Analysis (if enabled)
✅ Remediation Recommendations

Severity Levels

🔴 Critical: Immediate security threats (e.g., credential exposure, RCE)
🟠 High: Significant risks (e.g., unauthorized file access, SQLi)
🟡 Medium: Moderate concerns (e.g., information disclosure)
🟢 Low: Minor issues (e.g., verbose error messages)

⚙️ Configuration

Minimal Configuration

Create config/my-config.yaml:

# Use cases (test scenarios)
use_cases:
  - name: 'basic_security_scan'
    description: 'Basic security checks'
    tools: []  # No tool definitions needed!
    test_actions:
      - method: 'tools/list'
        timeout: 30
      - method: 'resources/list'
        timeout: 30
    expected_threats:
      - 'Unexpected tool exposure'
    duration: 120

# Optional: Claude AI settings
claude:
  api_key: null  # Set via CLAUDE_API_KEY environment variable

# Optional: Network monitoring
network:
  interface: 'any'
  max_packets: 50000

# Optional: Docker settings
docker:
  memory_limit: '1024m'
  cpu_limit: '1.0'

Creating Custom Use Cases

Add custom security tests to your configuration:

use_cases:
  - name: 'my_custom_test'
    description: 'Custom security test scenario'
    tools: []
    test_actions:
      # List available tools
      - method: 'tools/list'
        timeout: 30

      # Call specific tool
      - method: 'tools/call'
        tool_name: 'read_file'
        arguments:
          path: '/etc/passwd'
        timeout: 30

      # List resources
      - method: 'resources/list'
        timeout: 30

    expected_threats:
      - 'Unauthorized file access'
      - 'Sensitive data exposure'

    duration: 180

Available Test Methods

tools/list - List all available tools
tools/call - Execute a specific tool with arguments
resources/list - List available resources
resources/read - Read a specific resource
prompts/list - List available prompts
prompts/get - Get a specific prompt template

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                   MCP Security Analyzer CLI                  │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                  SimpleMCPOrchestrator                       │
│  • Coordinates security testing workflow                     │
│  • Manages Docker lifecycle                                  │
│  • Synchronizes packet capture with execution               │
└──────────┬────────────────────┬──────────────────┬──────────┘
           │                    │                  │
           ▼                    ▼                  ▼
┌──────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ SimpleMCPInspector│  │ PacketCapture   │  │ ClaudeAnalyzer │
│ • Runs MCP       │  │ • Network       │  │ • AI-powered   │
│   Inspector      │  │   monitoring    │  │   threat       │
│ • Executes tests │  │ • Deep packet   │  │   analysis     │
│ • Parses results │  │   inspection    │  │ • Remediation  │
└──────────────────┘  └─────────────────┘  └─────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│                     Docker Container                         │
│  ┌────────────────────────────────────────────────────────┐ │
│  │          MCP Inspector (Official Tool)                 │ │
│  │  • Protocol-compliant MCP client                       │ │
│  │  • Executes user's MCP server                          │ │
│  │  • Captures all MCP interactions                       │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │          User's MCP Server                             │ │
│  │  • Filesystem server, API client, database, etc.       │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│                    Security Reporter                         │
│  • Generates HTML/JSON/CSV reports                          │
│  • Severity classification                                  │
│  • Remediation recommendations                              │
└─────────────────────────────────────────────────────────────┘

🧪 Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test module
pytest tests/core/inspector/test_inspector_config.py -v

# Run integration tests (requires Docker)
pytest -m integration

Code Quality

# Format code
black src tests

# Sort imports
isort src tests

# Lint
flake8 src tests

# Type checking
mypy src

🔧 Troubleshooting

Docker Not Running

Error: Cannot connect to Docker daemon
Solution: Start Docker and verify with `docker version`

Permission Denied (Packet Capture)

Error: Permission denied when capturing packets
Solution: Run with sudo or add user to docker group

Use Case Not Found

Error: Use case 'my-test' not found in configuration
Solution: Check config file has the use case defined, or use example config:
  cp config/simple-usecases.yaml config/my-config.yaml

Claude API Error

Error: AI analysis failed: API key not configured
Solution: Set environment variable:
  export CLAUDE_API_KEY="your-key"
Or disable AI: --no-ai

MCP Inspector Not Found

Error: npx command not found in container
Solution: Ensure the Docker image includes Node.js and npm

📚 Additional Resources

MCP Specification: https://modelcontextprotocol.io/
MCP Inspector: https://github.com/modelcontextprotocol/inspector
Anthropic Claude API: https://www.anthropic.com/api
Docker Documentation: https://docs.docker.com/

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all tests pass (pytest)
Run code quality checks (black, isort, flake8, mypy)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔐 Security

This tool is designed for defensive security testing only. Please use responsibly and only on systems you have permission to test. Report security vulnerabilities privately to the project maintainers.

🙏 Acknowledgments

Anthropic for Claude API
Model Context Protocol for the MCP specification
MCP Inspector for the official testing tool
Scapy for packet manipulation and analysis
Docker for containerization technology

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Made with ❤️ for the security community

mcp-security-analyzer