consigcody94/metasploit-mcp-server

Metasploit MCP Server

    __  __      _                  _       _ _
   |  \/  | ___| |_ __ _ ___ _ __ | | ___ (_) |_
   | |\/| |/ _ \ __/ _` / __| '_ \| |/ _ \| | __|
   | |  | |  __/ || (_| \__ \ |_) | | (_) | | |_
   |_|  |_|\___|\__\__,_|___/ .__/|_|\___/|_|\__|
                            |_|
          __  __  ____ ____    ____
         |  \/  |/ ___|  _ \  / ___|  ___ _ ____   _____ _ __
         | |\/| | |   | |_) | \___ \ / _ \ '__\ \ / / _ \ '__|
         | |  | | |___|  __/   ___) |  __/ |   \ V /  __/ |
         |_|  |_|\____|_|     |____/ \___|_|    \_/ \___|_|

Overview

Metasploit MCP Server is a production-ready implementation of the Model Context Protocol that provides AI agents (Claude, GPT, etc.) with secure, controlled access to the Metasploit Framework for authorized penetration testing, security research, and CTF challenges.

Why This Project?

• AI-Powered Pentesting: Enable AI agents to conduct sophisticated security assessments
• Safe by Design: Built-in safety controls, dry-run mode, and audit logging
• Professional Grade: Rate limiting, connection pooling, and comprehensive error handling
• Fully Configurable: Whitelist/blacklist modules, control features, set limits

Features

Core Capabilities

Security Features

• Dry-Run Mode: Test workflows without actual exploitation
• Module Whitelist/Blacklist: Control which modules can be executed
• Rate Limiting: Prevent RPC API abuse
• Audit Logging: Track all operations for compliance
• Session Limits: Control maximum concurrent sessions
• SSL/TLS Support: Secure RPC communication

MCP Protocol Support

• 40+ Tools: Comprehensive coverage of Metasploit functionality
• 9 Resources: Real-time access to modules, sessions, and database
• 4 Prompts: Pre-built workflows for common scenarios
• Full Async: Non-blocking operations for better performance

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        AI Agent (Claude, GPT, etc.)              │
└─────────────────────────────┬───────────────────────────────────┘
                              │ MCP Protocol (stdio)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Metasploit MCP Server                        │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐        │
│  │   Tools (40+) │  │ Resources (9) │  │  Prompts (4)  │        │
│  └───────┬───────┘  └───────┬───────┘  └───────┬───────┘        │
│          │                  │                  │                 │
│  ┌───────▼──────────────────▼──────────────────▼───────┐        │
│  │              Safety & Audit Layer                    │        │
│  │  • Module filtering  • Rate limiting  • Audit logs   │        │
│  └───────────────────────┬─────────────────────────────┘        │
│                          │                                       │
│  ┌───────────────────────▼─────────────────────────────┐        │
│  │           Async Metasploit RPC Client               │        │
│  │  • Connection pooling  • Retry logic  • msgpack     │        │
│  └───────────────────────┬─────────────────────────────┘        │
└──────────────────────────┼──────────────────────────────────────┘
                           │ MSGRPC (msgpack over HTTP/HTTPS)
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Metasploit Framework                          │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐          │
│  │ Modules │  │ Sessions │  │   DB    │  │   Jobs   │          │
│  └─────────┘  └──────────┘  └─────────┘  └──────────┘          │
└─────────────────────────────────────────────────────────────────┘

Installation

Prerequisites

• Python 3.10 or higher
• Metasploit Framework with RPC enabled
• (Optional) PostgreSQL for Metasploit database

Using pip

pip install metasploit-mcp-server

From Source

git clone https://github.com/yourusername/metasploit-mcp-server.git
cd metasploit-mcp-server
pip install -e ".[dev]"

Using Docker

docker pull yourusername/metasploit-mcp-server
docker run -it --rm \
  -e METASPLOIT_MCP_MSF_HOST=host.docker.internal \
  -e METASPLOIT_MCP_MSF_PASSWORD=yourpassword \
  yourusername/metasploit-mcp-server

Quick Start

1. Start Metasploit RPC

# Start msfrpcd with a password
msfrpcd -P yourpassword -S -a 127.0.0.1

# Or from msfconsole
msf6> load msgrpc Pass=yourpassword

2. Configure the MCP Server

Create a .env file or set environment variables:

# .env
METASPLOIT_MCP_MSF_HOST=127.0.0.1
METASPLOIT_MCP_MSF_PORT=55553
METASPLOIT_MCP_MSF_PASSWORD=yourpassword
METASPLOIT_MCP_MSF_SSL=true
METASPLOIT_MCP_LOG_LEVEL=INFO

3. Run the Server

# Using the CLI
metasploit-mcp serve --password yourpassword

# Or with environment variables
metasploit-mcp serve

# Dry-run mode (safe testing)
metasploit-mcp serve --dry-run

4. Configure Your AI Client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "metasploit": {
      "command": "metasploit-mcp",
      "args": ["serve", "--password", "yourpassword"],
      "env": {
        "METASPLOIT_MCP_MSF_HOST": "127.0.0.1"
      }
    }
  }
}

Other MCP Clients

The server uses stdio transport. Connect using:

• Command: metasploit-mcp serve --password yourpassword
• Transport: stdio

Documentation

Available Tools

Available Resources

Available Prompts

Configuration Reference

All settings can be configured via environment variables with the METASPLOIT_MCP_ prefix:

Security

Important Notices

Warning: This tool provides access to powerful exploitation capabilities. Only use it:

• On systems you own or have explicit written authorization to test
• In isolated lab environments
• For authorized penetration testing engagements
• For CTF competitions and security research

Built-in Safeguards

1. Dry-Run Mode: Test workflows without actual exploitation
2. Module Filtering: Whitelist/blacklist specific modules
3. Rate Limiting: Prevent API abuse
4. Audit Logging: Complete operation trail
5. Session Limits: Control resource usage

Recommended Practices

# Always start in dry-run mode for testing
metasploit-mcp serve --dry-run

# Block dangerous modules in production
export METASPLOIT_MCP_BLOCKED_MODULES="exploit/multi/handler,auxiliary/dos/*"

# Enable full audit logging
export METASPLOIT_MCP_AUDIT_LOGGING=true

Examples

Basic Reconnaissance

# AI Agent interaction example
# 1. Search for scanner modules
result = await msf_search("type:auxiliary scanner/portscan")

# 2. Get module info
info = await msf_module_info("auxiliary", "scanner/portscan/tcp")

# 3. Run the scan
scan_result = await msf_execute(
    module_type="auxiliary",
    module_name="scanner/portscan/tcp",
    options={"RHOSTS": "192.168.1.0/24", "PORTS": "22,80,443"}
)

Vulnerability Check

# Check for EternalBlue without exploitation
result = await msf_check(
    module_type="exploit",
    module_name="windows/smb/ms17_010_eternalblue",
    options={"RHOSTS": "192.168.1.100"}
)

Session Interaction

# List sessions
sessions = await msf_sessions_list()

# Run command in Meterpreter
output = await msf_session_run(
    session_id=1,
    command="sysinfo"
)

# Get compatible post modules
modules = await msf_session_compatible_modules(session_id=1)

Development

Setup Development Environment

git clone https://github.com/yourusername/metasploit-mcp-server.git
cd metasploit-mcp-server
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pre-commit install

Running Tests

# Run all tests
pytest

# With coverage
pytest --cov=src/metasploit_mcp --cov-report=html

# Run specific test
pytest tests/test_client.py -v

Code Quality

# Format code
black src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

Contributing

Contributions are welcome! Please read our for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Acknowledgments

• Metasploit Framework - The world's most used penetration testing framework
• Model Context Protocol - Standardizing AI agent tool interfaces
• pymetasploit3 - Python Metasploit RPC client reference

Disclaimer

This tool is provided for educational and authorized security testing purposes only. The authors are not responsible for any misuse or damage caused by this tool. Always ensure you have proper authorization before conducting any security testing.