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:

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.

Related MCP server: mcp-pymetasploit3

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

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