MCP Security Framework (MCPSF)

Version: 0.4.0 Status: Production Ready

Professional security testing framework for Model Context Protocol (MCP) servers

Quick Start

Installation (Two Options)

Option 1: Direct Use (Recommended for most users)

git clone https://github.com/JoKFA/MCP-Security-Framework
cd MCP-Security-Framework
pip install -r requirements.txt

# Run assessments
python mcpsf.py assess <source>

Option 2: Editable Install (For contributors/developers)

git clone https://github.com/JoKFA/MCP-Security-Framework
cd MCP-Security-Framework
pip install -e .  # Installs in editable mode

# Run assessments
python mcpsf.py assess <source>

What's the difference?

Option 1: Installs only dependencies from requirements.txt
Option 2: Installs the package in editable mode (code changes take effect immediately, no reinstall needed)

Features

✅ Automatic Sandboxing - Zero-config Docker-based isolation (AMSAW v2)
✅ Multi-Source Support - npm packages, GitHub repos, local directories, remote URLs
✅ 14 Security Detectors - OWASP Top 10 coverage for MCP servers
✅ Professional Reports - JSON, SARIF (GitHub Security), CLI output

Architecture

5-phase pipeline that automatically sandboxes and tests MCP servers:

Discovery Engine - AST-based detection of MCP servers from any source
Container Provisioner - Docker provisioning with crash recovery and auto-fixes
Universal Bridge - Transport normalization (stdio/SSE → HTTP)
Security Assessment - 14 vulnerability detectors with 95%+ accuracy
Report Generation - Multi-format output (JSON, SARIF, CLI, audit logs)

Key Innovation: AMSAW v2 (Automatic MCP Sandbox And Wrapper) enables testing ANY MCP server with zero manual configuration.

Usage Examples

# Assess a local vulnerable MCP
python mcpsf.py assess targets/vulnerable/dv-mcp/challenges/easy/challenge1

# Assess an npm package
python mcpsf.py assess @modelcontextprotocol/server-time

# Assess a GitHub repository
python mcpsf.py assess https://github.com/modelcontextprotocol/servers/tree/main/src/time

# Run specific detectors
python mcpsf.py assess <source> --detectors MCP-2024-PI-001,MCP-2024-TP-001

# Custom output directory
python mcpsf.py assess <source> -o ./my-reports

# List all detectors
python mcpsf.py list-detectors

# Web UI for live monitoring
python mcpsf.py web

Documentation

📚 Complete Documentation

Detailed guides for different audiences:

Architecture Overview - System design and 5-phase pipeline
Wrapper Guide - AMSAW v2 automatic sandboxing
Detectors Guide - Security vulnerability detection
Reports Guide - Report formats and CI/CD integration
API Reference - CLI commands and Python API
Web View Guide - Flask web UI usage

Requirements

Python: 3.11+ recommended (tested with 3.11/3.12/3.13)
Node.js: 18+ for Node-based MCPs
Docker: 24+ with permission to run containers (required for sandboxing)
Package managers: pip or uv, plus npm
Resources: 4+ vCPU, 8GB RAM, 5GB free disk per assessment

System Metrics

| Metric | Value | |--------|-------| | Setup Time | 10-20 seconds | | Assessment Time | 30-90 seconds (avg) | | Success Rate | 100% (on working Python MCPs) | | Detectors | 14 | | Supported Languages | Python, Node.js | | Supported Transports | stdio, SSE |

Security Model

All MCP servers run in isolated Docker containers with:

Network isolation (bridge networking)
Rate limiting (SafeAdapter)
Scope enforcement (Policy engine)
Data redaction (automatic sensitive data removal)

License

MIT License - See LICENSE file for details

Contributing

See CONTRIBUTING.md for development setup, coding standards, and contribution guidelines.

Support

Issues: https://github.com/JoKFA/MCP-Security-Framework/issues
Documentation: docs/
Repository: https://github.com/JoKFA/MCP-Security-Framework

Built with ❤️ for the MCP security community

MCP Servers