Penetration Testing MCP Server

How to use

You will connect with an MCP client to your local MCP server and issue high-level actions such as performing a port scan, web directory enumeration, or vulnerability checks. The server coordinates the individual tools you choose and returns structured results you can review or feed into reports. Start by launching your MCP server locally, then configure your client with the provided stdio entry to run the server from Node.js. Use the client’s commands to start scans against your target, inspect results, and chain multiple tools for comprehensive reconnaissance. When you are ready, you can perform common operations like port discovery, directory enumeration, vulnerability lookups, and credential tests, all driven from your MCP client and routed through your local server.

How to install

Prerequisites you need before setting up the MCP server are: Linux or macOS (or Windows with WSL2), Node.js 18+ and npm, Python 3.8+ for certain tools, and Git.

# Create a working directory and move into it
mkdir mcp-pentest-server
cd mcp-pentest-server

# Initialize a Node.js project
npm init -y

# Install the MCP SDK and development utilities
npm install @modelcontextprotocol/sdk
npm install -D nodemon

# Optional: install other common tools and wordlists as needed (see prerequisites)

Claude Desktop Integration

Configure Claude Desktop to load your MCP server by creating or updating the MCP configuration with the following content.

{
  "mcpServers": {
    "pentest-server": {
      "command": "node",
      "args": ["/full/path/to/your/mcp-pentest-server/server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Usage examples in Claude Desktop

After you configure Claude Desktop, you can issue practical commands to perform standard reconnaissance tasks.

Please run an nmap scan on 192.168.1.1 using the quick scan type
Run a gobuster scan on http://example.com with php,html,txt extensions
Perform a nuclei scan on example.com focusing on CVE templates
Run a comprehensive scan on example.com including web and vulnerability scanning
Use hydra to brute force SSH on 192.168.1.100 with username admin and password list /usr/share/wordlists/rockyou.txt

Configuration options and security notes

You can tailor the server’s behavior with simple configuration tweaks. Consider defining custom wordlists, adjusting thread counts, and tuning timeouts to balance speed with stability. Apply best practices for security, including running with the principle of least privilege, validating inputs, and maintaining proper logging and isolated testing environments.

Troubleshooting

Common issues can arise during setup or while running scans. If you cannot locate a tool in PATH, verify it is installed and available in your shell. If you encounter permission errors, ensure you execute files with the appropriate permissions. When port access is blocked, run trusted scans in privileged environments or adjust your server startup accordingly.

# Check tool availability
which nmap
which gobuster

# Add to PATH if necessary
export PATH=$PATH:/usr/local/bin
```
```bash
# If permissions are required for the server script
sudo chmod +x server.js
sudo node server.js
```
```bash
# For privileged ports, run with elevated privileges if needed
sudo node server.js
```
```bash
# Enable debug logging during development
DEBUG=true node server.js

Advanced configuration

As you expand the MCP server, you can add new tools, store results in databases, and integrate with external APIs. Extend the server logic to run additional commands, persist results, and query threat intel services to enrich your scan data.

Security best practices

Follow security best practices to protect your testing environment: enforce least privilege, validate all inputs to prevent command injection, implement rate limiting, enable audit logging, isolate testing networks, encrypt sensitive results at rest, and keep all tools updated.

Legal considerations

Only test systems you own or have explicit written permission to assess, comply with local laws, document authorized testing activities, respect bug bounty scope rules, and protect data privacy throughout the engagement.

Support and contributing

For issues or improvements, follow standard channels to report problems, review related tool documentation, and contribute enhancements back to the project.

License

This project is licensed under the MIT License — see the LICENSE file for details.

nmap

Network mapper used for host discovery and port scanning to identify open ports and services.

gobuster

Directory and DNS enumeration tool to uncover hidden resources on web targets.

nikto

Web server scanner that checks for server configuration issues and vulnerabilities.

hydra

Password brute-forcing tool for testing the strength of authentication mechanisms.

john

Password cracker for offline or live password audits with support for multiple hash formats.

hashcat

High-performance password recovery tool leveraging GPUs for fast cracking.

ffuf

Fuzzy URL discovery and content enumeration tool for web applications.

dirsearch

Brute-force web content discovery tool to enumerate directories and files.

nuclei

Vulnerability scanner with templates for rapid identification of common issues.