An unofficial, modern, secure Model Context Protocol (MCP) server that provides AI assistants with controlled access to Metasploit Framework functionality.
Unofficial project — not affiliated with Rapid7. "Metasploit" is a trademark of Rapid7. This is an independent, community-maintained project with no affiliation, sponsorship, endorsement, or support from Rapid7. It is not an official Rapid7 or Metasploit product.
Fork notice: This project is a fork of GH05TCREW/MetasploitMCP, the original Metasploit MCP server created by GH05TCREW. Full credit for the original design and implementation goes to GH05TCREW; this fork contributes additional features and the PyPI release on top of that work. It is distributed under the same Apache License 2.0. See Relationship to upstream for what this fork changes and improves.
- Exploit Management: Search, configure, and execute Metasploit exploits
- Non-destructive checks:
check_vulnerabilityruns a module'scheckwithout exploiting - Payload Generation: Create custom payloads with advanced encoding options
- Session Management: Control active sessions with command execution
- Listener Management: Start and manage reverse handlers
- Workspace database intelligence: Read hosts, services, vulnerabilities, notes, credentials, and loot from the Metasploit database
- Async results: Retrieve results of long-running module runs with
get_module_results
- Tool annotations: every tool advertises
readOnly/destructivehints - Structured output: typed results with a text fallback for older clients
- Resources:
msf://server/infoandmsf://module/{module}documentation - Elicitation: optional client confirmation before destructive actions
See docs/MCP_API.md for the full tool/resource reference, MCP specification conformance, and a comparison with the official Rapid7 MCP.
- Optional safe mode: offensive tools (exploit/module execution, payload generation, session/listener control) are enabled by default (this is an offensive tool). Harden a deployment with
--safe-mode(orMSF_MCP_ALLOW_DANGEROUS=false) to expose read-only tools only. (This intentionally inverts the official Rapid7 server's default-off posture to avoid regressing existing users.) - Optional rate limiting: off by default; enable a per-minute cap with
--rate-limit N - Optional confirmation:
--confirm-dangerousasks the client to approve each destructive action via MCP elicitation - Bind Address Validation: Rejects bind addresses that are neither a wildcard nor an IP configured on the host
- Input Sanitization: Comprehensive validation of all parameters, including rejection of control characters in module options (command-injection guard)
- Error Handling: Prevents information leakage through proper error management
⚠️ Binding default is0.0.0.0(all interfaces) for compatibility, not security. Reverse-handler listeners default to binding all interfaces so payloads on remote targets can connect back. This is intentional for offensive use but is not a locked-down default — on a shared or untrusted network, restrict it by passing an explicitreverselistenerbindaddress(e.g. a specific interface IP).
- Poetry Dependency Management: Modern Python packaging and dependency resolution
- Comprehensive Testing: 92+ tests covering unit, integration, and security scenarios
- Type Hints: Full type annotation support for better IDE experience
- FastMCP HTTP Transport: Modern HTTP-based MCP protocol implementation
- Development Tools: Integrated linting, formatting, and type checking
- Python 3.10+ (3.11+ recommended)
- Poetry for dependency management (Installation Guide)
- Metasploit Framework with RPC enabled
From PyPI (recommended):
pip install metasploit-mcpThis installs the metasploit-mcp CLI. To try it without installing into your
environment, use pipx: pipx run metasploit-mcp --help.
From source (for development):
git clone https://github.com/setuidloot/MetasploitMCP.git
cd MetasploitMCP
poetry install
poetry shell# Start Metasploit RPC service
msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553
# Or from msfconsole
msfconsole -q
msf6 > load msgrpc ServerHost=127.0.0.1 ServerPort=55553 User=msf Pass=yourpasswordexport MSF_PASSWORD=yourpassword
export MSF_SERVER=127.0.0.1
export MSF_PORT=55553
export PAYLOAD_SAVE_DIR=/path/to/save/payloads
export MSF_RPC_PROTOCOL=msgpack # Options: 'msgpack' (default) or 'jsonrpc'RPC Protocol Options:
msgpack(default): Uses MessagePack binary serialization (faster, more compact)jsonrpc: Uses JSON-RPC protocol (human-readable, easier to debug)
# Full toolset (default) — offensive tools enabled
metasploit-mcp --transport http --host 127.0.0.1 --port 8085
# Hardened: read-only tools only
metasploit-mcp --transport http --safe-mode
# Optional: require client confirmation before each destructive action
metasploit-mcp --transport http --confirm-dangerous
# Optional: cap dangerous requests per minute
metasploit-mcp --transport http --rate-limit 60
# From source
poetry run metasploit-mcp --transport stdio
make run # or: make run-debugBy default the server exposes the full toolset (offensive tools enabled). Pass
--safe-mode(or setMSF_MCP_ALLOW_DANGEROUS=false) to expose read-only tools only. See docs/MCP_API.md for the full safety model.
# Complete development environment setup
make dev-setup
# Or manually
poetry install
poetry run pre-commit install
make test# Show all available commands
make help
# Quick development workflow
make quick-check # Format, lint, and quick test
make full-check # Complete quality check with coverage
# Testing
make test # Run all tests
make test-coverage # Run with coverage report
make test-watch # Watch mode for development
# Code quality
make format # Format code with black
make lint # Run linting checks
make type-check # Run type checkingMetasploitMCP/
├── src/
│ └── metasploit_mcp/ # Main package
│ ├── __init__.py # Package entry point with main()
│ ├── server.py # MCP server implementation
│ ├── event_loop_monitor.py # Async event loop monitoring
│ ├── instance_manager.py # Metasploit instance management
│ └── jsonrpc_patch.py # pymetasploit3 JSON-RPC patch
├── scripts/ # Utility scripts
│ ├── bump_version.py # Version bumping
│ ├── run_tests.py # Test runners
│ └── ...
├── tests/ # Comprehensive test suite
│ ├── conftest.py # Pytest fixtures
│ ├── harness.py # Metasploitable3 test harness
│ └── test_*.py # Test modules
├── docs/ # Documentation
│ ├── API.md # Complete API reference
│ ├── DEVELOPMENT.md # Development guide
│ ├── TROUBLESHOOTING.md # Common issues and solutions
│ ├── METASPLOITABLE3_TESTING.md # Integration testing guide
│ └── QUICK_START_TESTING.md # Quick start for testing
├── examples/ # Example scripts
├── pyproject.toml # Poetry configuration
├── Makefile # Development commands
├── CHANGELOG.md # Version history
└── CONTRIBUTING.md # Contribution guidelines
Configure claude_desktop_config.json (after pip install metasploit-mcp):
{
"mcpServers": {
"metasploit": {
"command": "metasploit-mcp",
"args": [
"--transport", "stdio"
],
"env": {
"MSF_PASSWORD": "yourpassword",
"MSF_SERVER": "127.0.0.1",
"MSF_PORT": "55553"
}
}
}
}Add "--safe-mode" to the args to expose read-only tools only. If you installed
from source instead of PyPI, use "command": "poetry" with
"args": ["run", "metasploit-mcp", …] and a "cwd" pointing at the checkout.
For HTTP-based MCP clients:
# Start HTTP server
metasploit-mcp --transport http --host 0.0.0.0 --port 8085
# MCP endpoint: http://your-server:8085/mcpIMPORTANT: This tool provides direct access to Metasploit Framework capabilities. Use responsibly and only in authorized environments.
- Bind Address Validation: Rejects addresses that are neither a wildcard nor a host-configured IP
- Input Sanitization: All parameters are validated before processing; control characters in module options are rejected (command-injection guard)
- Error Handling: Prevents information disclosure through proper error management
⚠️ Listeners bind0.0.0.0(all interfaces) by default — a compatibility choice for catching reverse connections, not a hardened default. Pass an explicitreverselistenerbindaddressto restrict the binding on shared/untrusted networks.
- Only use in authorized testing environments
- Restrict listener bind addresses (
reverselistenerbindaddress) when you don't need all interfaces - Validate all commands before execution
- Monitor generated payloads and their usage
- Use strong passwords for Metasploit RPC
- Regularly update dependencies
| Tool | Description | Key Parameters |
|---|---|---|
list_exploits |
Search exploit modules | platform_filter, search_term |
run_exploit |
Execute exploits | module_name, options, payload_name |
generate_payload |
Create payloads | payload_type, format_type, options |
start_listener |
Start handlers | payload_type, lhost, lport |
list_active_sessions |
Show sessions | None |
send_session_command |
Execute commands | session_id, command |
- Modern src layout: Proper Python package structure
- CLI entry point:
metasploit-mcpcommand - Bind Address Control:
reverse_listener_bind_addressparameter - Port Binding:
reverse_listener_bind_portparameter - IP Validation: Automatic validation of bind addresses
- FastMCP Transport: Modern HTTP-based MCP protocol
For complete API documentation, see docs/API.md.
# All tests with coverage
make test-coverage
# Quick test run
make test-quick
# Watch mode for development
make test-watch
# Specific test categories
make test-unit # Unit tests only
make test-integration # Integration tests onlyThe project maintains high test coverage with 92+ tests covering:
- Unit Tests: Individual function testing
- Integration Tests: End-to-end workflow testing
- Security Tests: Bind address validation and input sanitization
- Error Handling: Comprehensive error scenario testing
Coverage reports are generated in htmlcov/index.html.
Test MetasploitMCP against real vulnerable targets using the included test harness:
# List available exploit tests
poetry run python tests/harness.py --list-tests
# Run all tests against Metasploitable 3
poetry run python tests/harness.py \
--target 10.0.2.15 \
--lhost 10.0.2.4 \
--lport 4444
# Run specific test
poetry run python tests/harness.py \
--target 10.0.2.15 \
--lhost 10.0.2.4 \
--test "ProFTPD ModCopy Exec"The harness includes tests for:
- ProFTPD ModCopy Exec
- Apache Shellshock
- Drupal Drupageddon
- phpMyAdmin RCE
- Ruby on Rails ActionPack
- UnrealIRCd Backdoor
For detailed documentation, see:
- API Reference: Complete tool documentation with examples
- Development Guide: Setup, testing, and contribution guidelines
- Troubleshooting: Common issues and solutions
- Integration Testing: Testing with Metasploitable 3
- Quick Start Testing: 5-minute testing setup
- Poetry Migration: Migration from requirements.txt
- Releasing: How maintainers cut a release
- Changelog: Version history and breaking changes
- Contributing: How to contribute to the project
- src Layout: Package moved to
src/metasploit_mcp/ - CLI Entry Point: Use
metasploit-mcpcommand - Import Path: Use
from metasploit_mcp import ...
# Pull latest changes
git pull
# Reinstall dependencies
poetry install
# Run tests to verify
make testFor detailed migration information, see docs/POETRY_MIGRATION.md.
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Set up development environment:
make dev-setup - Make changes and add tests
- Run quality checks:
make full-check - Submit a pull request
This project is a fork of GH05TCREW/MetasploitMCP,
the original Metasploit MCP server created by GH05TCREW (harmasic@gmail.com). Full credit for the
original design and implementation goes to the upstream author. This fork retains the upstream
Apache License 2.0 (see LICENSE and NOTICE).
Upstream base (GH05TCREW): core Metasploit RPC integration, exploit / payload / session / console
management, and background job handling — originally a single-file server with a requirements.txt
install and SSE transport.
What this fork changes and improves:
- Packaging & distribution — Poetry-based packaging, a
src/metasploit_mcp/layout, ametasploit-mcpCLI entry point (replacing the single-filerequirements.txtsetup), and the first PyPI release of the project (pip install metasploit-mcp). - Transport — FastMCP HTTP (streamable) transport, replacing SSE.
- Dynamic option detection — module/payload options are queried live from Metasploit instead of being hardcoded, with detection of confused module/payload options.
- Concurrency safety — per-session locking to prevent concurrent Meterpreter/shell access, plus a per-agent Metasploit instance manager for isolation.
- Reliability — async event-loop monitoring (blocking/backlog detection), MCP keep-alive to
prevent client timeouts, an RPC timeout cap with client cleanup and
auth.logout, session-ID normalization with fallback lookups, and force-option validation against module capabilities. - Quality — a comprehensive test suite, a Metasploitable 3 integration harness, and dependency security updates.
See CHANGELOG.md for the detailed version history.
This project is licensed under the Apache License 2.0 — see the LICENSE file for the
full text and the NOTICE file for attribution. As a fork, it preserves the license of the
upstream GH05TCREW/MetasploitMCP project.
- GH05TCREW/MetasploitMCP: The original project this fork is based on — full credit to GH05TCREW for the core design and implementation
- Metasploit Framework: The powerful penetration testing platform, by Rapid7 (this project is unaffiliated with and unsupported by Rapid7)
- Model Context Protocol: The standardized AI-tool communication protocol
- FastMCP: Modern MCP server implementation framework
- Poetry: Modern Python dependency management
Disclaimer: This tool is for authorized security testing only. Users are responsible for ensuring they have proper authorization before using this tool in any environment.