msf-mcp

A minimal MCP (Model Context Protocol) server that exposes the Metasploit Framework to Claude Code (or any MCP-compatible client) through msfrpcd.

⚠️ Use only in environments you are authorized to test — your own lab, your own infrastructure, or an engagement you have explicit written permission for. This project is a thin wrapper around Metasploit's own documented RPC API; it doesn't add capability beyond what your installed Metasploit already has, but it does let an LLM drive it, so treat it with the same care you'd give any pentest tooling.

How it works

The project is split into two scripts, on purpose:

Script	Runs as	Needs sudo?	Purpose
setup.py	you, manually	yes	Starts msfrpcd. If it's already running, stops it and starts a fresh instance; otherwise just starts it.
server.py	Claude Code	no	Connects to the already-running msfrpcd over RPC and exposes it as MCP tools.

you  --sudo-->  setup.py  --spawns-->  msfrpcd
                                            ^
                                            | RPC (msgpack)
                                            |
Claude Code  --stdio-->  server.py  -------┘

Keeping the privileged piece (setup.py) separate from the MCP server (server.py) means Claude Code never needs to run with elevated privileges, and the process an LLM is driving has no more access than a normal RPC client would.

Requirements

• Metasploit Framework installed, with msfrpcd on PATH
• Python 3.9+
• pip install -r requirements.txt (installs mcp and pymetasploit3)

Installation

git clone https://github.com/IMApurbo/msf-mcp.git
cd msf-mcp
pip install -r requirements.txt

Configure

Both setup.py and server.py have a CONFIG block near the top:

RPC_HOST = "127.0.0.1"
RPC_PORT = 55553
RPC_PASSWORD = "change-me-123"
USE_SSL = True

Edit both files and make sure these four values match in each. There's no shared config file on purpose — it keeps each script standalone and easy to read.

Start msfrpcd

sudo python3 setup.py

This will:

• start msfrpcd if it isn't running, or
• stop and cleanly restart it if it already is

Logs go to /var/log/msf_setup.log and to stdout. You can also run explicit actions:

sudo python3 setup.py status
sudo python3 setup.py start
sudo python3 setup.py stop
sudo python3 setup.py restart

Register the MCP server with Claude Code

claude mcp add metasploit -- python3 /full/path/to/server.py

Using a virtualenv? Just point at that interpreter instead:

claude mcp add metasploit -- /path/to/venv/bin/python /full/path/to/server.py

Check it registered:

claude mcp list

Verifying it works

Ask Claude Code:

Use the metasploit debug_connection_check tool and tell me the result.

A healthy response looks like:

{
  "configured_host": "127.0.0.1",
  "configured_port": 55553,
  "tcp_port_reachable": true,
  "rpc_login_ok": true,
  "rpc_error": null,
  "log_file": "/tmp/msf_mcp_server.log"
}

• tcp_port_reachable: false → msfrpcd isn't running — run sudo python3 setup.py.
• tcp_port_reachable: true but rpc_login_ok: false → something's listening on that port, but login failed — usually a RPC_PASSWORD mismatch between setup.py and server.py. Check rpc_error for details.

Available tools

Tool	Description
debug_connection_check	Reports whether the server can reach and authenticate to msfrpcd
debug_tail_log	Returns the last N lines of the server's own log file
list_module_names	List module names by type (exploit/auxiliary/post/payload/encoder/nop)
search_modules	Keyword search across Metasploit modules
module_info	Description, options, and targets for a module
run_module	Configure and execute an exploit/auxiliary/post module
list_jobs / kill_job	Manage background jobs (handlers, running scans)
list_sessions	List active shell/meterpreter sessions
session_run_command	Send a command to a session and read the output
session_kill	Terminate a session
console_execute	Run a raw msfconsole command (fallback for anything not covered above)
console_list / console_destroy	Manage msfconsole instances

Debugging

server.py logs everything to /tmp/msf_mcp_server.log and to stderr — never stdout, since Claude Code uses stdout for the MCP protocol itself. If a tool call fails or behaves unexpectedly:

tail -f /tmp/msf_mcp_server.log

or ask Claude directly to call the debug_tail_log tool — no terminal access needed.

setup.py logs to /var/log/msf_setup.log.

Project structure

msf-mcp/
├── setup.py         # privileged: starts/stops/restarts msfrpcd (run manually with sudo)
├── server.py        # unprivileged: MCP server exposing Metasploit as tools (added to Claude Code)
├── requirements.txt
└── README.md

License

MIT

Author

IMApurbo