Metasploit-MCP
# Metasploit-MCP
Connect AI agents to local Metasploit through MCP. Includes 23 tools for RPC,
modules, sessions, jobs, consoles, native terminals, and files.
Use only on systems you are authorized to test.
## Installation
### Requirements
- Python 3.11+, [uv](https://docs.astral.sh/uv/), and Git.
- [Metasploit Framework](https://docs.metasploit.com/) installed, with `msfrpcd` on your PATH.
- An AI client that supports local MCP servers.
Supports macOS, Linux, and Windows 10 (1809+) / Windows 11.
### 1. Install
```sh
git clone https://github.com/ethanroubal/Metasploit-MCP.git
cd Metasploit-MCP
uv sync --frozen
```
### 2. Add the MCP server
**ChatGPT desktop — through the app:**
1. Open **Settings → MCP servers → Add server** and choose **STDIO**.
2. Enter these settings:
| Field | Value |
| --- | --- |
| Name | `metasploit` |
| Command | `uv` (`uv.exe` on Windows) |
3. Add each argument below as a **separate entry**, in this order:
```text
--directory
/absolute/path/to/Metasploit-MCP
run
--frozen
metasploit-mcp
--launch-rpc
```
The directory must be this cloned project, not `msfconsole` or the Metasploit
installation. Keep the entire path in one entry, including any spaces.
4. Replace the project path with your clone's absolute path, then **Save** and
select **Restart**.
Alternatively, use the [TOML configuration](examples/mcp-chatgpt.toml) for
ChatGPT desktop / Codex. ChatGPT in a browser requires the separate tunnel setup
in the [ChatGPT setup guide](docs/chatgpt.md).
**Clients that use JSON:** add this entry to your AI client's MCP configuration:
```json
{
"mcpServers": {
"metasploit": {
"command": "uv",
"args": [
"--directory", "/absolute/path/to/Metasploit-MCP",
"run", "--frozen", "metasploit-mcp", "--launch-rpc"
]
}
}
}
```
Replace the project path with your clone's absolute path. If you already have
MCP servers configured, add `metasploit` inside the existing `mcpServers` object.
**Windows:** use `uv.exe` and a path such as `C:/Users/you/Metasploit-MCP`.
See the [Windows configuration](examples/mcp-windows.json).
### 3. Connect
Restart your AI client and ask it to call `msf_status`. A successful response shows
the Metasploit version.
The client starts the MCP server and local RPC daemon automatically. Each connection
gets a free local port and temporary credentials, so multiple chats can run at once.
The bridge stops its own daemon on shutdown. Automatic startup
requires a recent Metasploit release; for an existing or older daemon, follow
[these instructions](docs/reference.md#connect-to-an-existing-rpc-daemon).
## Usage
Ask your AI client to use the Metasploit tools. For example:
- “Check the Metasploit version and list running jobs.”
- “Search for HTTP auxiliary modules and show their options.”
- “Create a console, run `version`, read the output, and close it.”
- “List the available sessions.”
You do not need to start the MCP server manually when using the configuration
above. Metasploit must be installed separately; database operations also need a
configured Metasploit database.
### Troubleshooting
- **Command not found:** use absolute paths for `uv` and `msfrpcd`. Append
`"--msfrpcd", "/path/to/msfrpcd"` to the configuration's `args` if needed.
- **Desktop setup:** enter each argument separately. If Metasploit is installed
under `/opt/metasploit-framework`, add `--msfrpcd` and
`/opt/metasploit-framework/bin/msfrpcd` as two more argument entries. For slow
startup, set `startup_timeout_sec = 120` using the [TOML example](examples/mcp-chatgpt.toml).
- **Port already in use:** remove `MSF_RPC_URL` from an automatic-startup
configuration to choose a free port, or connect to the running daemon using the
[existing-daemon configuration](examples/mcp.json).
### More information
- [Advanced setup, tool reference, and development](docs/reference.md)
- [Feature coverage and limitations](docs/coverage.md)
- [MCP configuration examples](examples/)
TDQS
Scored across 23 tools
Tools are organized into clean families (console, process, file, module, RPC) with descriptions that explicitly distinguish risky pairs, e.g. msf_console_* (RPC daemon state) vs msf_process_* (local PTY executables). The remaining overlap is intentional: msf_rpc is a documented catch-all that can do most of what msf_sessions, msf_jobs, msf_status, and msf_module_execute do, which can tempt misselection but is clearly framed as an escape hatch.
Nearly all tools follow a predictable msf_<family>_<verb> snake_case pattern (msf_console_create, msf_process_signal, msf_file_read, msf_module_execute). A few are bare nouns without a verb (msf_sessions, msf_jobs, msf_status, msf_rpc), a minor deviation but still readable and unambiguous within their families.
23 tools is on the heavy side, but the count is driven by a few genuinely stateful subsystems (7 process lifecycle tools, 5 console tools) where read/write/signal/close genuinely each earn a place. No tool appears redundant or filler; a slightly flatter surface could merge some list-only endpoints.
Core areas are covered (module search/info/execute, console lifecycle, process and file I/O), but sessions and jobs are list-only and must be driven through raw msf_rpc for interaction, stopping, or data read — a notable gap in the typed surface for Metasploit's central post-exploitation workflow. File tools also lack delete/move, though the generic RPC escape hatch prevents true dead ends.