Metasploit-MCP connects AI agents to a local Metasploit Framework instance via MCP, exposing 23 tools for status/RPC access, modules, sessions/jobs, consoles, local processes, and files.
Check Metasploit/API status and version.
Discover RPC methods, Ruby signatures, and auth requirements.
Call arbitrary Metasploit RPC methods with positional arguments, binary/map encoding, and timeouts.
Search modules, inspect module metadata, and execute modules with datastore options.
List running jobs and available sessions.
Create, list, write to, read from, and destroy persistent msfconsole consoles.
Start and manage local processes with PTY or pipe mode, including read/write, signals, resize, list, and close.
Read, write, and list local files as base64 chunks for binaries, loot, scripts, modules, and artifacts.
Includes destructive/mutating actions: module execution, session/RPC operations, file writes, process control, and possible daemon shutdown; use only on authorized systems.
Connects AI agents to a local Metasploit Framework instance, providing tools for arbitrary RPC calls, module search/info/execution, job and session management, persistent consoles, native process and interactive terminal control, and local file access.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Metasploit-MCP scan 192.168.1.100 for open ports"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Python 3.11+, uv, and Git.
Metasploit Framework installed, with msfrpcd on your PATH.
An AI client that supports local MCP servers.
Supports macOS, Linux, and Windows 10 (1809+) / Windows 11.
git clone https://github.com/ethanroubal/Metasploit-MCP.git
cd Metasploit-MCP
uv sync --frozenChatGPT desktop — through the app:
Open Settings → MCP servers → Add server and choose STDIO.
Enter these settings:
Field | Value |
Name |
|
Command |
|
Add each argument below as a separate entry, in this order:
--directory
/absolute/path/to/Metasploit-MCP
run
--frozen
metasploit-mcp
--launch-rpcThe directory must be this cloned project, not msfconsole or the Metasploit
installation. Keep the entire path in one entry, including any spaces.
Replace the project path with your clone's absolute path, then Save and select Restart.
Alternatively, use the TOML configuration for ChatGPT desktop / Codex. ChatGPT in a browser requires the separate tunnel setup in the ChatGPT setup guide.
Clients that use JSON: add this entry to your AI client's MCP configuration:
{
"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.
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.
Related MCP server: MSFConsole MCP Server
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.
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.
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.
Create a persistent msfconsole and return its ID; destroy it when finished.
Inputs: options. Returns: object
Destroy a console by ID. This does not stop its background jobs/sessions.
Inputs: console_id (required). Returns: object
List consoles and their busy state.
Inputs: no named parameters. Returns: object
Consume available console output; returns data, prompt, and busy status.
Reads drain the console's output buffer. busy=false is a snapshot, not proof that a just-submitted command has completed or that a job has ended.
Inputs: console_id (required). Returns: object
Send arbitrary console commands, including multiline scripts.
The console retains state (selected module, options, workspace). This tool only submits input; read output separately. A newline is appended by default.
Inputs: command (required), console_id (required), append_newline. Returns: object
List a local directory with pagination to locate scripts and output artifacts.
Inputs: path (required), limit, offset. Returns: object
Read a local file as lossless base64 chunks; continue using next_offset.
Use for generated binaries, loot, reports, resource scripts, or modules. This accesses the MCP host's filesystem with its OS permissions.
Inputs: path (required), offset, max_bytes. Returns: object
Write text or {$binary: base64} at a local file byte offset.
Creates missing parent directories and files. truncate=true clears an existing file first; use only on the first chunk when replacing a file. Supports arbitrary-sized resource scripts, modules, and import artifacts by writing successive chunks at next_offset. Paths are local to the MCP host.
Inputs: data (required), path (required), offset, truncate. Returns: object
List running jobs. Use msf_rpc job.info or job.stop with a job ID.
Inputs: no named parameters. Returns: object
Execute an installed module with its datastore options; returns job/UUID or output.
Inspect module.info and module.options first. Execution may continue after this tool returns. Poll job.list, module.running_stats, or module.results using msf_rpc. Binary output is represented as a $binary base64 object.
Inputs: options (required), module_name (required), module_type (required). Returns: object
Return module metadata. Use msf_rpc module.options for its option schema.
Inputs: module_name (required), module_type (required). Returns: object
Search Metasploit modules using its search syntax (e.g. type:auxiliary name:http).
Inputs: query (required). Returns: object
Stop this process and owned descendants, release its PTY, and delete output.
Detached descendants are tracked by ancestry and an inherited ownership marker. Retrieve output first. Owned processes are also stopped when the MCP server shuts down. This does not stop an external RPC daemon.
Inputs: process_id (required). Returns: object
List processes owned by this bridge and their exit status.
Inputs: no named parameters. Returns: object
Read lossless spooled output at a byte offset, without consuming it.
data is base64 bytes; text is a display-only UTF-8 decoding. Use next_offset to continue reading. Pipe mode separates stdout/stderr; PTY merges them into stdout. eof means the process exited and this stream has been read. A process timeout/cancellation never implicitly replays or stops it.
Inputs: process_id (required), offset, stream, max_bytes. Returns: object
Resize a persistent PTY and notify its foreground terminal program.
Inputs: rows (required), columns (required), process_id (required). Returns: object
Signal the process group: interrupt, terminate, kill, stop, or continue.
Accepts named POSIX signals, including SIGINT, SIGTERM, SIGKILL, SIGSTOP, SIGCONT, SIGHUP, SIGUSR1, SIGUSR2, and SIGWINCH. SIGINT interrupts native console/IRB work. It may exit a standalone tool.
Inputs: process_id (required), signal_name. Returns: object
Start a local executable with literal argv, without a shell.
Use ["msfconsole", "-q"] with terminal=true for a real interactive PTY, including IRB, prompts, and terminal input. Use ["msfvenom", "--help"] with terminal=false for exact binary output and separate stderr. Other installed Framework utilities and interpreters can be run the same way. These processes do not share the RPC daemon's in-memory sessions or jobs. Returns immediately with process_id. Read output, write input, signal, resize, and close using the process tools. cwd and env are optional.
Inputs: argv (required), cwd, env, rows, +2 more. Returns: object
Write text or {$binary: base64} to stdin, without adding a newline.
For commands include a newline explicitly. Control characters can be sent directly in PTY mode (e.g. for Ctrl-C, for EOF). In pipe mode, close_stdin=true sends EOF after data. PTY stdin cannot be closed separately.
Inputs: process_id (required), data, close_stdin. Returns: object
Call ANY Metasploit RPC method with positional arguments, excluding its auth token.
Examples: core.version []; module.info ["auxiliary", "module/name"]; job.list []; session.list []; db.workspaces []; plugin.loaded []. Methods and arguments depend on your installed Metasploit version. authenticated=null detects auth.login and health.check as unauthenticated; false omits the token for other noauth endpoints. timeout overrides the per-request HTTP timeout in seconds, without retrying a failed action. For binary arguments use an exact {"$binary": "base64..."} object. For typed map keys or literal marker objects use {"$map": [[key, value], ...]}. Non-string map keys in results are preserved using the same pair-list form. This can mutate state, execute modules, manage sessions, or stop the daemon. Use console tools for functionality without an RPC method.
Inputs: method (required), params, timeout, authenticated. Returns: object
Find RPC method names, Ruby argument signatures, and authentication requirements.
Defaults to a bundled reference catalog pinned to an upstream commit. Pass the installed Framework root to scan its source instead. This is source discovery, not a live capability probe; plugins and versions can differ. The catalog never restricts msf_rpc calls to unlisted methods.
Inputs: limit, query, offset, framework_root. Returns: object
List sessions; use msf_rpc session.* methods to interact with them.
Inputs: no named parameters. Returns: object
Authenticate and get Metasploit and API version information.
Inputs: no named parameters. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Context and control for any AI. Agent identity, scoped access, and proof across tools.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
