Metasploit MCP Server

How to use

You connect an MCP client to the server using either the HTTP/SSE transport or the STDIO transport. The server exposes tools to list exploits and payloads, run exploits and auxiliary modules, manage sessions, and handle listeners and payload generation. Start with a local STDIO-based workflow or connect remotely via HTTP/SSE for broader integration.

How to install

Prerequisites you need before installation: Metasploit Framework installed and msfrpcd running, Python 3.10 or higher, and the required Python packages listed in requirements.txt.

Step-by-step installation and setup:

# 1) Install Metasploit Framework and start RPC server
# Ensure msfrpcd is installed and can be started
msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553

# 2) Install MCP server dependencies
pip install -r requirements.txt

# 3) (Optional) Set environment variables for payload storage
export PAYLOAD_SAVE_DIR=/path/to/save/payloads

# 4) Start the MCP server in STDIO mode via the provided entrypoint
# This example uses the STDIO transport configuration shown in the integration snippet
# If using the wrapper, you would run the command below through that wrapper as configured
{ "command": "uv", "args": ["--directory", "C:\\path\\to\\MetasploitMCP", "run", "MetasploitMCP.py", "--transport", "stdio"], "env": {"MSF_PASSWORD": "yourpassword"} }

# 5) Alternative: run directly with Python if you’re not using the wrapper
python MetasploitMCP.py --transport stdio

# 6) If you want HTTP/SSE transport for MCP clients, start the server in HTTP mode (example)
python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

# 7) Ensure the client connects to the right endpoint (SSE) at the server URL, e.g. http://<server-ip>:8085/sse

Configuration options

Payloads generated by the server are saved to a directory you can customize. The default location is a payloads directory in your home folder, but you can override this with the PAYLOAD_SAVE_DIR environment variable.

# Example environment variable to override payload save location
export PAYLOAD_SAVE_DIR=/custom/path/to/payloads

# Windows PowerShell example
$env:PAYLOAD_SAVE_DIR = "C:\\custom\\path\\to\\payloads"

# Claude Desktop integration can also set this in the env block of the MCP config
{
  "env": {
    "MSF_PASSWORD": "yourpassword",
    "PAYLOAD_SAVE_DIR": "C:\\your\\actual\\path\\to\\payloads"
  }
}

Security Considerations

This MCP server provides direct access to Metasploit Framework capabilities. Use only in environments where you have explicit permission to perform security testing. Validate inputs before execution and operate in segregated test environments when possible. Be mindful that post-exploitation commands can modify target systems.

Additional notes

Tools exposed by the server include: list_exploits, list_payloads, run_exploit, run_auxiliary_module, run_post_module, generate_payload, list_active_sessions, send_session_command, terminate_session, list_listeners, start_listener, and stop_job. These endpoints enable you to discover modules, execute actions, manage sessions, and control listeners, all through MCP clients.

Troubleshooting tips

If you cannot connect via HTTP/SSE, verify that msfrpcd is running with the expected credentials and that the MCP server is started with the correct transport. For STDIO, ensure the wrapper or command you use matches the configuration shown in the integration example. Check that the required Python packages are installed and that the PAYLOAD_SAVE_DIR path exists if you override the default location.

list_exploits

Search and list available Metasploit exploit modules.

list_payloads

Search and list available Metasploit payload modules with optional platform/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 (saves files 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

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