pentest-mcp-server by kanekitakitos - MCP Server

🛡️ Security Testing MCP Server 🛡️

A secure bridge between AI assistants and Kali Linux pentesting tools via Docker's MCP protocol.

This project provides a server that exposes a suite of powerful penetration testing tools through a Machine-to-Cloud Protocol (MCP) gateway. It allows AI assistants, scripts, or other automated systems to perform authorized security assessments in a controlled and auditable manner.

⚠️ LEGAL WARNING: This MCP server provides access to professional penetration testing tools. Use it ONLY on systems you own or have explicit written authorization to test. Unauthorized security testing is illegal and unethical. The user is solely responsible for their actions.

Core Concept

This server acts as a bridge between an MCP client (like an AI Chatbot) and a containerized environment equipped with standard Kali Linux security tools. The project's foundation is Docker's MCP Gateway. This innovative tool from Docker provides the protocol and the base server that makes it possible to expose local command-line tools securely to external clients.

Our pentest-mcp-server extends this gateway by packaging a curated set of penetration testing tools into a single, easy-to-deploy Docker container. By sending simple requests to the server, a client can orchestrate complex security scans without needing direct access to the underlying shell or the tools themselves.

The Role of Docker

Docker is central to this project for three key reasons:

Environment Consistency: The Dockerfile defines a complete, self-contained environment based on Kali Linux, with all security tools and Python dependencies pre-installed. This ensures the server runs identically everywhere, from a developer's laptop to a production machine.
Isolation and Security: The tools run inside a sandboxed container, isolated from the host operating system. This prevents a potentially compromised tool from affecting the host machine.
Simplified Deployment: Users don't need to manually install and configure each penetration testing tool. A single docker run command is all it takes to get the entire suite of tools up and running.

Features

The server exposes the following industry-standard tools. All inputs are sanitized to mitigate command injection risks.

Tool Function	Command Exposed	Description
Network Scanner	`nmap_scan`	Performs network port scanning and service detection.
Web Scanner	`nikto_scan`	Scans web servers for known vulnerabilities.
SQL Injection	`sqlmap_test`	Automates SQL injection and database takeover tests.
WordPress Scanner	`wpscan_scan`	Scans WordPress sites for vulnerabilities.
Content Discovery	`dirb_scan`	Discovers hidden web content and directories.
Exploit Search	`searchsploit_search`	Searches the Exploit Database for known exploits.
Tech Fingerprinting	`whatweb_scan`	Identifies web technologies used by a site.
Fast Content Discovery	`gobuster_dir`	Brute-forces directories and files with high speed.
WAF Detection	`wafw00f_detect`	Detects the presence of a Web Application Firewall.
Fast Port Scanner	`masscan_fast`	Performs extremely fast TCP port scanning.

Prerequisites

Docker: Docker Desktop or Docker Engine installed and running.
System Resources: At least 4GB of RAM allocated to Docker is recommended.
Authorization: You must have explicit, written permission to conduct security testing on any target systems.

Installation & Running the Server

Click to expand Installation Steps

Clone the repository: (Remember to replace your-username with your actual GitHub username)

git clone https://github.com/your-username/pentest-mcp-server.git
cd pentest-mcp-server

Build the Docker image:

docker build -t pentest-mcp-server:latest .

Run the server container:

The following command starts the server in detached mode, maps the required port, and gives it the necessary privileges to run some of the scanning tools effectively.
```
docker run -d --name pentest-mcp-server -p 8811:8811 --privileged pentest-mcp-server:latest
```
The server will now be running and listening for MCP connections on localhost:8811.

Testing the Server

Click to expand Server Testing Guide

To help test that the MCP server is running correctly and to inspect the tools it exposes, you can use the MCP Inspector. It's a useful utility for debugging and interacting with MCP servers.

Run the MCP Inspector:

npx @modelcontextnpx @modelcontextprotocol/inspector

Connect to the server: This command launches a web interface. Connect it to your local server, which by default is http://localhost:8811. You will be able to see all the available tools and their schemas, and even test them directly from the UI.

Test Server

Click to expand Remote Server Testing Guide (via SSH Tunnel)

If your MCP server is running on a remote machine, you can securely connect to it for testing by creating an SSH tunnel. This forwards the server's port on the remote machine to your local machine, allowing the MCP Inspector to connect as if the server were running locally.

Create the SSH Tunnel: On your local machine, run the following command. Replace user@remote-server-ip with your SSH credentials for the remote machine.
```
ssh -L 8811:localhost:8811 user@remote-server-ip
```
This command maps port 8811 on your local machine to port 8811 on the remote server.
Test with MCP Inspector: Now, you can follow the local testing guide. Run npx @modelcontextnpx @modelcontextprotocol/inspector and connect it to http://localhost:8811. Your requests will be securely forwarded to the remote server.

Test Server

Connecting a Client

Click to expand Client Connection Guides

To interact with the server, you need an MCP-compatible client. Here are a couple of ways to do it:

Using Docker Desktop's MCP Toolkit

If you are using Docker Desktop, you can add your pentest-mcp-server as a managed tool server. This makes its tools available to any client integrated with Docker Desktop's MCP capabilities.

Ensure the server is running: Make sure your container is running.
Add the server using the Docker CLI: Open your terminal and run the following command to register your local server with Docker.
```
docker mcp add pentest-server http://localhost:8811
```
Verify the server is added: You can list all configured MCP servers to confirm it was added successfully.
```
docker mcp ls
```
You should see pentest-server in the list. Now, clients connected to Docker Desktop can use the tools provided by your server.

Google Gemini CLI

Alternatively, you can use a standalone client. A great free and open-source option is the Google Gemini CLI. It's a command-line tool that can be configured to use local tools through an MCP gateway like this one.

Install the Gemini CLI following the instructions in its repository.
Configure it to connect to your pentest-mcp-server. You will typically need to set the tool endpoint to http://localhost:8811.

Use it by asking Gemini to run a tool from your server:

gemini "use nmap_scan to perform a quick scan on 192.168.1.1"

Usage Examples

Once the server is running, you can connect an MCP-compatible client (such as an AI assistant with the appropriate plugins) and issue commands in natural language.

"Scan 192.168.1.1 with nmap to find open ports."
"Run a nikto scan on http://example.local."
"Test http://testsite.local/login.php for SQL injection vulnerabilities."
"Use dirb to find hidden directories on http://testserver.local."
"Search searchsploit for apache 2.4 exploits."
"Identify web technologies on http://target.local with whatweb."
"Detect if http://website.local is protected by a WAF."

Architecture

graph TD
    subgraph "User's Machine"
        A[🤖 MCP Client e.g., Gemini CLI] -- "1. Natural Language Request" --> B{Docker Desktop / MCP Router};
    end

    B -- "2. MCP Tool Call (JSON)" --> C[<br><b>pentest-mcp-server</b> Container<br>Listening on port 8811];
    
    subgraph C
        D[🐍 pentest_server.py] -- "3. Sanitize & Execute" --> E[Kali Tool e.g., nmap];
        E -- "4. Raw Output" --> D;
    end

    D -- "5. Formatted Response" --> B;
    B -- "6. Final Result" --> A;

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

Acknowledgments

This project would not be possible without the innovative MCP Gateway project by the team at Docker.