Metasploit MCP Server
Provides tools to execute Metasploit commands, search exploits, get module information, list modules, run Nmap scans, and perform vulnerability scans through the Metasploit Framework.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Metasploit MCP Server Search for Apache Log4j exploits"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Metasploit MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with secure access to Metasploit Framework functionality through a standardized interface. This server wraps core Metasploit capabilities into MCP tools that can be discovered and used by compatible clients.
Features
š§ Execute Metasploit commands - Run raw Metasploit commands with built-in security validation
š Search exploits - Find exploits by name, CVE, or keyword
š Module information - Get detailed information about any Metasploit module
š¦ List modules - Browse available modules by type (exploits, auxiliaries, payloads, etc.)
š Network scanning - Run Nmap scans through Metasploit's database integration
š Vulnerability scanning - Execute vulnerability scans against target systems
ā¹ļø Version information - Check your Metasploit installation details
š”ļø Security controls - Input sanitization and command injection prevention
Related MCP server: MSFConsole MCP Server
Requirements
Node.js 16.0.0 or higher
Metasploit Framework installed and accessible via command line (
msfconsole)MCP-compatible client (Claude Desktop, VS Code with MCP extension, etc.)
Installation
Clone the repository:
git clone https://github.com/RobertoDure/metasploit-mcp-server.git cd metasploit-mcp-serverInstall dependencies:
npm installVerify Metasploit installation:
msfconsole --version
Usage
Development Mode
npm run devProduction Mode
npm startThe server communicates via STDIO transport, making it compatible with any MCP client that supports this transport method.
Available Tools
The MCP server exposes the following tools through the @modelcontextprotocol/sdk:
Tool Name | Description | Required Parameters | Optional Parameters |
| Execute raw Metasploit commands with security validation |
| None |
| Search for exploits by name, CVE, or keywords |
| None |
| Get detailed information about a specific module |
| None |
| List available modules by type |
| None |
| Get Metasploit Framework version information | None | None |
| Execute Nmap scans through Metasploit's database |
|
|
| Run vulnerability scans using auxiliary modules |
| None |
Tool Details
execute-command
Executes any valid Metasploit command
Includes input sanitization to prevent command injection
Runs in quiet, non-interactive mode for consistent output
Timeout protection (30 seconds)
search-exploit
Searches Metasploit's exploit database
Supports CVE numbers, exploit names, and keywords
Returns formatted results with module paths and descriptions
module-info
Provides comprehensive module information
Includes options, targets, payloads, and references
Works with any module type (exploits, auxiliaries, etc.)
list-modules
Lists modules by category with validation
Supports all major module types
Returns organized module listings
run-nmap-scan
Integrates with Metasploit's database features
Supports custom Nmap options
Stores results in Metasploit database for further analysis
run-vuln-scan
Uses auxiliary scanner modules
Currently implements SMB MS17-010 (EternalBlue) scanning
Can be extended for additional vulnerability checks
Example Usage
When connected to an MCP-compatible client, you can interact with Metasploit using natural language:
Searching and Information:
"Search for Apache Log4j exploits"
"Show me details about the EternalBlue exploit (exploit/windows/smb/ms17_010_eternalblue)"
"List all available Windows payloads"
"What auxiliary modules are available?"
Scanning and Reconnaissance:
"Run an Nmap scan against 192.168.1.100"
"Perform a stealth scan on 10.0.0.0/24 with -sS -O options"
"Check if 192.168.1.50 is vulnerable to MS17-010"
System Information:
"What version of Metasploit am I running?"
"Execute the 'help' command to see available commands"
Sample Responses
The server returns structured JSON responses:
{
"success": true,
"output": "Metasploit Framework Console Output...",
"command": "search apache"
}Or in case of errors:
{
"success": false,
"output": "Command contains potentially dangerous characters",
"error": "Security violation"
}Architecture
The server follows a clean, modular architecture:
src/
āāā index.js # Main MCP server with tool registrations
āāā services/
āāā metasploit-service.js # Metasploit Framework integration layer
tests/
āāā metasploit-service.test.js # Unit tests with JestKey Components
McpServer: Uses
@modelcontextprotocol/sdkfor MCP protocol implementationMetasploitService: Encapsulates all Metasploit interactions with security controls
StdioServerTransport: Handles communication via STDIO for client compatibility
Zod Schemas: Provides runtime type validation for all tool inputs
Security Features
Input Sanitization: Removes dangerous shell characters (
;&|$()`)Command Validation: Ensures commands are non-empty strings
Timeout Protection: 30-second timeout on all command executions
Error Handling: Comprehensive error responses with structured formatting
Module Type Validation: Strict validation for module type parameters
Configuration
Package Configuration
The server is configured as an ES module with the following key settings:
{
"name": "metasploit-mcp-server",
"version": "1.0.0",
"type": "module",
"main": "src/index.js",
"engines": {
"node": ">=16.0.0"
}
}Dependencies
Production Dependencies:
@modelcontextprotocol/sdk(^1.12.0) - MCP protocol implementationzod(^3.22.4) - Runtime type validation and schema definition
Development Dependencies:
jest(^29.7.0) - Testing framework with ES module supporteslint(^8.57.0) - Code linting and style enforcement
MCP Client Configuration
For Claude Desktop, add to your MCP settings:
{
"mcpServers": {
"metasploit": {
"command": "node",
"args": ["src/index.js"],
"cwd": "/path/to/metasploit-mcp-server"
}
}
}For VS Code with MCP extension:
{
"mcpServers": {
"metasploit-mcp-server": {
"command": "npm",
"args": ["start"],
"cwd": "/path/to/metasploit-mcp-server"
}
}
}Security Considerations
ā ļø Important Security Notice
This MCP server provides direct access to Metasploit Framework capabilities. Please observe these security guidelines:
š Access Control
No built-in authentication - Consider adding authentication for production use
Local access recommended - Avoid exposing this server to untrusted networks
Principle of least privilege - Run with minimal required system permissions
š”ļø Built-in Security Features
Command sanitization - Prevents command injection attacks
Input validation - All parameters are validated using Zod schemas
Timeout protection - 30-second execution limits prevent hanging processes
Error isolation - Failures are contained and don't crash the server
āļø Legal and Ethical Considerations
Authorization required - Only use against systems you own or have explicit permission to test
Responsible disclosure - Follow responsible disclosure practices for discovered vulnerabilities
Compliance - Ensure usage complies with local laws and organizational policies
Documentation - Maintain records of authorized testing activities
š§ Recommended Deployment Practices
Run in isolated/sandboxed environments
Use dedicated testing networks
Implement network-level access controls
Monitor and log all activities
Regular security updates for dependencies
šØ Risk Awareness
Commands executed have the same privileges as the user running the server
Metasploit modules can perform invasive actions on target systems
Some modules may cause service disruption or system instability
Always test in non-production environments first
Development
Scripts
# Start in development mode with file watching
npm run dev
# Run production server
npm start
# Run tests with Jest
npm test
# Run tests in watch mode
npm run test:watch
# Lint code with ESLint
npm run lint
# Fix linting issues automatically
npm run lint:fixTesting
The project includes comprehensive Jest tests:
# Run all tests
npm test
# Generate coverage report
npm test -- --coverage
# Watch mode for development
npm run test:watchTest coverage includes:
ā Command execution validation
ā Security sanitization
ā Error handling
ā Module type validation
ā Input validation edge cases
Project Structure
metasploit-mcp-server/
āāā src/
ā āāā index.js # MCP server entry point
ā āāā services/
ā āāā metasploit-service.js # Metasploit integration
āāā tests/
ā āāā metasploit-service.test.js # Unit tests
āāā package.json # Dependencies and scripts
āāā jest.config.json # Jest testing configuration
āāā README.md # DocumentationExtending the Server
Adding New Tools
To add new Metasploit capabilities:
Add a method to MetasploitService:
async myNewFeature(param) { return this.executeCommand(`my_command ${param}`); }Register the tool in index.js:
server.registerTool("my-new-tool", { title: "My New Tool", description: "Description of what it does", inputSchema: { param: z.string().describe("Parameter description") } }, async ({ param }) => { const result = await metasploitService.myNewFeature(param); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; });Add tests:
describe('myNewFeature', () => { it('should execute the new feature', async () => { // Test implementation }); });
Custom Module Integration
For specific module integrations, you can create specialized methods:
async scanForWebVulns(target) {
const commands = [
`use auxiliary/scanner/http/dir_scanner`,
`set RHOSTS ${target}`,
`run`,
`back`
].join('; ');
return this.executeCommand(commands);
}Error Handling Patterns
Follow the established error handling pattern:
if (!param || typeof param !== 'string') {
return {
success: false,
output: 'Invalid parameter',
error: 'Validation failed'
};
}Troubleshooting
Common Issues
Metasploit not found:
# Ensure Metasploit is in PATH
which msfconsole
# Or check installation
msfconsole --versionPermission errors:
# Check file permissions
ls -la src/index.js
# Ensure Node.js has execution rights
chmod +x src/index.jsModule import errors:
Verify
"type": "module"is set inpackage.jsonUse
.jsextensions in all import statementsCheck Node.js version (requires >=16.0.0)
MCP client connection issues:
Verify STDIO transport is being used correctly
Check that the server starts without errors
Ensure the client configuration points to the correct path
Debug Mode
Enable debug logging by setting environment variables:
DEBUG=mcp* npm startPerformance Tuning
For better performance with large scans:
// Increase timeout for long-running operations
const { stdout, stderr } = await execAsync(fullCommand, {
timeout: 60000 // 60 seconds
});License
MIT License - see LICENSE file for details.
Contributing
Contributions are welcome! Please follow these guidelines:
Fork the repository and create a feature branch
Write tests for new functionality
Follow the existing code style (use ESLint)
Update documentation as needed
Submit a pull request with a clear description
Development Workflow
# Clone your fork
git clone https://github.com/yourusername/metasploit-mcp-server.git
# Install dependencies
npm install
# Create a feature branch
git checkout -b feature/new-tool
# Make changes and test
npm test
npm run lint
# Commit and push
git commit -m "Add new tool for X"
git push origin feature/new-toolCode Standards
Use ES modules (
import/export)Follow JSDoc documentation style
Maintain test coverage above 80%
Use meaningful variable and function names
Handle errors gracefully with structured responses
Happy hacking! šš
Available Tools
7 toolsexecute-commandExecute Metasploit CommandC
Execute a raw Metasploit command
Inputs: command (required).
get-versionGet VersionA
Get Metasploit version information
Inputs: no named parameters.
list-modulesList ModulesB
List available modules by type
Inputs: type (required).
module-infoModule InformationC
Get information about a specific Metasploit module
Inputs: modulePath (required).
run-nmap-scanRun Nmap ScanC
Run a nmap scan using Metasploit
Inputs: target (required), options.
run-vuln-scanRun Vulnerability ScanC
Run a vulnerability scan on a target
Inputs: target (required).
search-exploitSearch ExploitsB
Search for exploits by name or CVE
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 7 tools
Most tools have clearly distinct purposes: versioning, raw command execution, module discovery, and scanning are separate concerns. Some overlap exists between search-exploit and list-modules, and between run-nmap-scan and run-vuln-scan, but the descriptions are clear enough to avoid major misselection.
Tool names mostly follow a hyphenated verb_noun pattern like get-version, search-exploit, and list-modules. The name module-info deviates by leading with a noun instead of a verb, and run- is repeated twice, but the overall convention is consistent and readable.
Seven tools is a well-scoped size for a Metasploit-oriented server. Each tool represents a meaningful capability without unnecessary duplication or bloat, and the count fits comfortably within the ideal range.
The tool surface covers discovery, information gathering, scanning, and raw command execution, which are core Metasploit workflows. However, there are notable gaps in high-level exploit execution, session management, and workspace/database controls, leaving agents reliant on the generic execute-command for these important actions.
Related MCP Connectors
Find, vet, and run MCP tools through a secure audited gateway with prompt-injection risk scoring
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
Real-time CVE, exploit, and vulnerability intelligence for AI assistants (350K+ CVEs, 115K+ PoCs)
AI pentesting: run scans, triage vulnerabilities, review PRs, manage schedules and assets.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides a bridge between large language models and the Metasploit Framework, enabling AI assistants to access and control penetration testing functionality through natural language.765Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables secure integration with Metasploit Framework for AI assistants, providing comprehensive access to penetration testing tools, module management, payload generation, and database operations. Designed for authorized security testing and defensive analysis with 28 specialized tools covering complete MSF functionality.8MIT
- -licenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to interact with Metasploit Framework through 28 comprehensive tools for penetration testing and security analysis. Provides secure, structured access to MSF modules, database operations, session management, and payload generation capabilities.2-
- AlicenseNot gradedqualityDmaintenanceBridges large language models with the Metasploit Framework to enable natural language control over penetration testing workflows. It provides tools for searching modules, executing exploits, generating payloads, and managing active sessions.1Apache 2.0