MCP Server, specs and documentation by cdelafuente-r7 · Pull Request #21315 · rapid7/metasploit-framework

cdelafuente-r7 · 2026-04-16T16:05:36Z

The Metasploit MCP Server (msfmcpd) provides AI applications with secure, structured access to Metasploit Framework data through the Model Context Protocol (MCP). It acts as a middleware layer between AI clients (such as Claude, Cursor, or custom agents) and Metasploit, exposing 8 standardized tools for querying reconnaissance data and searching modules. The implementation relies on the official Ruby SDK for MCP (here).

This initial implementation is read-only. Only tools that query data (modules, hosts, services, vulnerabilities, etc.) are available. Tools for module execution, session interaction, and database modifications will be added in a future iteration.

All the details can be found in the documentation here.

Copilot

Pull request overview

Adds an initial read-only Metasploit MCP Server (msfmcpd) implementation that exposes Metasploit data via MCP tools, plus supporting config/loading, RPC auto-start, logging, and a broad test suite (unit + integration).

Changes:

Introduces MCP server wrapper + 8 MCP tools (module search/info, DB hosts/services/vulns/notes/creds/loot).
Adds Metasploit RPC clients (MessagePack + JSON-RPC), response transformation, rate limiting, config loading/validation, and optional sanitized file logging.
Adds extensive RSpec coverage, WebMock-based integration tests, config fixtures/examples, and wires new dependencies (mcp, webmock).

Reviewed changes

Copilot reviewed 60 out of 61 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
spec/lib/msfmcp/security/rate_limiter_spec.rb	Unit tests for token-bucket rate limiter + concurrency behavior.
spec/lib/msfmcp/metasploit/client_spec.rb	Tests for protocol selection and delegation in client facade.
spec/lib/msfmcp/mcp/tools/vulnerability_info_spec.rb	Tests MCP tool contract/behavior for vulnerability queries.
spec/lib/msfmcp/mcp/tools/service_info_spec.rb	Tests MCP tool contract/behavior for service queries.
spec/lib/msfmcp/mcp/tools/search_modules_spec.rb	Tests MCP tool contract/behavior for module searching + pagination.
spec/lib/msfmcp/mcp/tools/note_info_spec.rb	Tests MCP tool contract/behavior for note queries.
spec/lib/msfmcp/mcp/tools/module_info_spec.rb	Tests MCP tool contract/behavior for module details.
spec/lib/msfmcp/mcp/tools/loot_info_spec.rb	Tests MCP tool contract/behavior for loot queries.
spec/lib/msfmcp/mcp/tools/host_info_spec.rb	Tests MCP tool contract/behavior for host queries.
spec/lib/msfmcp/mcp/tools/credential_info_spec.rb	Tests MCP tool contract/behavior for credential queries.
spec/lib/msfmcp/logging/logger_spec.rb	Tests redaction + log-level filtering for file logger.
spec/lib/msfmcp/errors_spec.rb	Tests inheritance/structure of new error classes.
spec/integration/msfmcpd/tool_execution_search_spec.rb	End-to-end tool execution through HTTP stubs (module search).
spec/integration/msfmcpd/tool_execution_db_spec.rb	End-to-end tool execution through HTTP stubs (DB tools).
spec/integration/msfmcpd/rate_limiting_spec.rb	Integration coverage for rate limiting across tool calls.
spec/integration/msfmcpd/messagepack_auth_flow_spec.rb	Integration coverage for MessagePack auth + token reuse.
spec/integration/msfmcpd/jsonrpc_auth_flow_spec.rb	Integration coverage for JSON-RPC bearer auth behavior.
spec/integration/msfmcpd/error_handling_spec.rb	Integration coverage for network/auth/API error conversions.
spec/integration/msfmcpd/config_loading_spec.rb	Integration coverage for config defaults + env/CLI overrides.
spec/file_fixtures/config_files/msfmcpd/valid_messagepack.yaml	Fixture config for MessagePack-mode integration tests.
spec/file_fixtures/config_files/msfmcpd/valid_jsonrpc.yaml	Fixture config for JSON-RPC-mode integration tests.
msfrpcd	Allows RPC credentials to be provided via environment variables.
msfmcpd	Adds executable wrapper to run the MCP server application.
metasploit-framework.gemspec	Adds runtime dependency on the MCP Ruby SDK gem.
lib/msfmcp/security/rate_limiter.rb	Implements token-bucket rate limiter with mutex for concurrency.
lib/msfmcp/security/input_validator.rb	Adds input validation helpers (query/ports/protocol/pagination/etc.).
lib/msfmcp/rpc_manager.rb	Adds auto-start management for local `msfrpcd` lifecycle.
lib/msfmcp/metasploit/response_transformer.rb	Converts RPC responses into MCP-friendly structured output.
lib/msfmcp/metasploit/messagepack_client.rb	Implements MessagePack RPC client with retry + logging hooks.
lib/msfmcp/metasploit/jsonrpc_client.rb	Implements JSON-RPC client using bearer token auth.
lib/msfmcp/metasploit/client.rb	Facade that selects MessagePack vs JSON-RPC implementation.
lib/msfmcp/mcp/tools/vulnerability_info.rb	MCP tool implementation for vulnerabilities query.
lib/msfmcp/mcp/tools/service_info.rb	MCP tool implementation for services query.
lib/msfmcp/mcp/tools/search_modules.rb	MCP tool implementation for module searching.
lib/msfmcp/mcp/tools/note_info.rb	MCP tool implementation for notes query.
lib/msfmcp/mcp/tools/module_info.rb	MCP tool implementation for module details.
lib/msfmcp/mcp/tools/loot_info.rb	MCP tool implementation for loot query.
lib/msfmcp/mcp/tools/host_info.rb	MCP tool implementation for hosts query.
lib/msfmcp/mcp/tools/credential_info.rb	MCP tool implementation for credentials query.
lib/msfmcp/mcp/server.rb	Wraps MCP server startup and stdio/http transports with logging hooks.
lib/msfmcp/logging/logger.rb	Adds opt-in JSONL file logger with recursive sanitization.
lib/msfmcp/errors.rb	Defines error taxonomy across config/security/metasploit/mcp layers.
lib/msfmcp/config/validator.rb	Adds config validation for core msf_api + mcp settings.
lib/msfmcp/config/loader.rb	Loads YAML config, applies defaults, supports env overrides.
lib/msfmcp.rb	Main library entrypoint requiring all MCP/server components.
docs/navigation.rb	Adds MCP server doc page to documentation navigation.
config/mcp_config_jsonrpc.yaml.example	Example JSON-RPC config for MCP server.
config/mcp_config.yaml.example	Example MessagePack config for MCP server.
Gemfile.lock	Adds `mcp` and test deps (`webmock` and transitive gems).
Gemfile	Adds `webmock` to test group for HTTP stubbing in specs.

smcintyre-r7

I tried to hook it up to a running Metasploit instance, and it's possible I'm doing something wrong but I couldn't get it to connect, it just hangs.

smcintyre-r7 · 2026-04-16T20:35:07Z

+
+require 'yaml'
+
+module MsfMcp


Now that we're merging this into framework to keep it side by side, it might make the most sense to name it to Msf::MCP and move to lib/msf/core/mcp since it's the MCP daemon equivalent of the RPC daemon at Msf::RPC at lib/msf/core/rpc.

smcintyre-r7 · 2026-04-16T20:37:14Z

+    class Logger
+      SENSITIVE_PATTERNS = {
+        password: /password[\"']?\s*[:=]\s*[\"']?[^\"',\s}]+/i,
+        token_keyval: /token[\"']?\s*[:=]\s*[\"']?[^\"',\s}]+/i,
+        token_header: /token\s+[a-zA-Z0-9_\-\.]+/i,
+        api_key: /api[_-]?key[\"']?\s*[:=]\s*[\"']?[^\"',\s}]+/i,
+        secret: /secret[_-]?key[\"']?\s*[:=]\s*[\"']?[^\"',\s}]+/i,
+        credential: /credential[\"']?\s*[:=]\s*[\"']?[^\"',\s}]+/i,
+        auth: /auth[\"']?\s*[:=]\s*[\"']?[^\"',\s}]+/i,
+        bearer: /bearer\s+[a-zA-Z0-9_\-\.]+/i
+      }.freeze
+
+      REDACTED = '[REDACTED]'


This probably needs to stay here for now though I could definitely see it being helpful in the future. The rest of this module though should use Rex::Logging now that it's available. That'll let us swap sinks and use the same logging subsystem as the rest of MSF.

smcintyre-r7 · 2026-04-16T20:41:24Z

+#   MCP_TRANSPORT               MCP server transport type ('stdio' or 'http')
+#   MCP_HOST                    MCP server host
+#   MCP_PORT                    MCP server port


We could definitely be running parallel to other MCP servers so we should namespace these under MSF_ like the others are.

smcintyre-r7 · 2026-04-16T20:42:20Z

+#   MSF_API_PASSWORD            Metaspoit RPC API password (for MessagePack auth)
+#   MSF_API_TOKEN               Metaspoit RPC API token (for JSON-RPC auth)
+#   MSF_AUTO_START_RPC          Auto-start Metasploit RPC server ('true' or 'false')
+#   MCP_TRANSPORT               MCP server transport type ('stdio' or 'http')


This one's pretty helpful, would you mind make accepting it as a flag too? e.g. --mcp-transport http

Starting the MCP server with HTTP means the user can start it interactively and handle all the invocation setup with RVM and the current environment, privileges etc and just paste the URL into the AI client.

cdelafuente-r7 · 2026-04-17T12:42:29Z

Thank you @smcintyre-r7 for your review and testing. The hang you observed seems to be related to the MSF RPC daemon itself. The connection times out and I could reproduce the same issue using the msfrpc client:

./msfrpc -a 127.0.0.1 -p 55552 -U msf -P DNBN6QQp
[nothing happens]

I didn't know there were a msfconsole plugin for RPC and didn't test it. I always started it with msfrpcd or letting the MCP server start it.

Also, I'm looking into implementing your suggestions right now.

cdelafuente-r7 added docs feature rn-enhancement release notes enhancement labels Apr 16, 2026

smcintyre-r7 added this to Metasploit Kanban Apr 16, 2026

github-project-automation bot moved this to Todo in Metasploit Kanban Apr 16, 2026

cdelafuente-r7 marked this pull request as draft April 16, 2026 16:18

cdelafuente-r7 force-pushed the mcp-server branch from 2879f3e to 4745002 Compare April 16, 2026 17:28

cdelafuente-r7 marked this pull request as ready for review April 16, 2026 17:28

MCP Server, specs and documentation

04ffe3c

cdelafuente-r7 force-pushed the mcp-server branch from 4745002 to 04ffe3c Compare April 16, 2026 17:31

smcintyre-r7 self-assigned this Apr 16, 2026

smcintyre-r7 requested a review from Copilot April 16, 2026 17:42

smcintyre-r7 linked an issue Apr 16, 2026 that may be closed by this pull request

Add a read-only MCP server to Metasploit #21269

Open

Copilot started reviewing on behalf of smcintyre-r7 April 16, 2026 17:43 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

smcintyre-r7 requested changes Apr 16, 2026

View reviewed changes

github-project-automation bot moved this from Todo to Waiting on Contributor in Metasploit Kanban Apr 16, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MCP Server, specs and documentation#21315

MCP Server, specs and documentation#21315
cdelafuente-r7 wants to merge 1 commit intorapid7:masterfrom
cdelafuente-r7:mcp-server

cdelafuente-r7 commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

smcintyre-r7 left a comment

Uh oh!

smcintyre-r7 Apr 16, 2026

Uh oh!

smcintyre-r7 Apr 16, 2026

Uh oh!

smcintyre-r7 Apr 16, 2026

Uh oh!

smcintyre-r7 Apr 16, 2026

Uh oh!

cdelafuente-r7 commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

cdelafuente-r7 commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

smcintyre-r7 left a comment

Choose a reason for hiding this comment

Uh oh!

smcintyre-r7 Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

smcintyre-r7 Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

smcintyre-r7 Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

smcintyre-r7 Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

cdelafuente-r7 commented Apr 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants