Metasploit MCP Server

How to use

Start the MCP server so your MCP client can talk to Metasploit Framework. You have two transport options: HTTP/SSE for most clients or STDIO for direct pipe connections with tools like Claude Desktop. Connect your client to the HTTP endpoint to use the common SSE channel, or run the STDIO mode to communicate over standard input/output.

In practical terms, you will typically: list exploits and payloads, choose and configure an exploit, start or stop listeners, generate payloads, and manage sessions. You can also run auxiliary and post modules, as well as send commands to active sessions. When you need to interoperate with Claude Desktop, you configure the desktop client to launch the MCP server in STDIO mode and point it to the local Python script that runs the server.

Security-conscious workflows are supported by explicit environment variables for authentication and payload storage. Always run in a controlled environment with proper authorization. Review commands before executing, since exploitation and post-exploitation actions can modify systems.

How to install

Prerequisites you need on your machine: Python 3.10 or higher.

Install the MCP server software by cloning the project and installing dependencies.

Install runtime dependencies with the Python package manager.

Configure environment variables as needed for your Metasploit access and payload saving location.

Start the Metasploit RPC service and run the MCP server in your preferred transport mode (HTTP/SSE or STDIO). Follow the commands below to get started.

# Prerequisites: ensure msfrpcd is running and Python 3.10+
# Install dependencies from requirements.txt
pip install -r requirements.txt

# Optional environment configuration (examples)
# MSF_PASSWORD=yourpassword
# MSF_SERVER=127.0.0.1
# MSF_PORT=55553
# MSF_SSL=false
# PAYLOAD_SAVE_DIR=/path/to/save/payloads

# Start the Metasploit RPC service (example)
msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553

# Run the MCP server in HTTP mode (example)
python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

# Or run the MCP server in STDIO mode (example)
python MetasploitMCP.py --transport stdio

# Claude Desktop integration uses the STDIO path via a wrapper script
# See integration steps under Claude Desktop Integration for details

Claude Desktop integration and other notes

To integrate with Claude Desktop, configure a client profile that launches the MCP server in STDIO mode using the Python script. This enables Claude to interact with Metasploit through the same toolset used by other MCP clients.

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

Security considerations

This MCP server provides direct access to Metasploit Framework capabilities. Use responsibly and only in environments where you have explicit permission to perform security testing. Always validate commands before execution and operate in isolated or authorized test environments. Be aware that post-exploitation commands can modify target systems.

Example workflows

Basic exploitation workflow involves listing exploits, selecting one, running it against a target, and then interacting with any resulting sessions.

Post-exploitation workflows let you run post modules on existing sessions, issue commands in a session, and cleanly terminate sessions when finished.

Handler management includes starting a listener to receive connections, listing active listeners, and stopping a running job when you are done.

Configuration options

Payloads generated via the server can be saved to a configured directory. You can set an environment variable to override the default path where payloads are stored.

# Default save location example (adjust as needed)
PAYLOAD_SAVE_DIR=/path/to/payloads

list_exploits

Search and list available Metasploit exploit modules

list_payloads

Search and list available Metasploit payload modules with optional platform and architecture filtering

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

generate_payload

Generate payload files using Metasploit RPC and save them locally

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

End an active session

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