Habeeba6120/Pentest-MCP

🔒 Penetration Testing MCP Server

A Model Context Protocol (MCP) server that provides educational penetration testing capabilities through a secure Docker container running Kali Linux tools. Designed for authorized security testing and cybersecurity education.

🎯 Overview

This MCP server integrates professional penetration testing tools into Claude Desktop, allowing AI-assisted security assessments in controlled environments. All tools run in an isolated Docker container with proper input sanitization and security measures.

⚡ Features

🛠️ Security Tools Included

🔐 Security Features

• 🐳 Containerized Environment - Isolated Kali Linux container
• 🛡️ Input Sanitization - Prevents command injection attacks
• 👤 Non-root Execution - Runs as unprivileged user pentester
• 🔍 Target Validation - IP/domain format verification
• ⏱️ Timeout Protection - Prevents hanging scans
• 📝 Comprehensive Logging - Full audit trail

🚀 Quick Start

Prerequisites

• Docker Desktop installed and running
• Claude Desktop application
• Git (for cloning the repository)

Installation

1. Clone the repository

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

2. Build the Docker image

   docker build -t pentest-mcp-server .
   

3. Configure Claude Desktop

   Edit your Claude Desktop config file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   Add this configuration:

   {
     "mcpServers": {
       "pentest_docker": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "--cap-add=NET_RAW",
           "--cap-add=NET_ADMIN",
           "pentest-mcp-server",
           "python3",
           "pentest_server.py"
         ]
       }
     }
   }
   

4. Restart Claude Desktop

   Completely quit and restart Claude Desktop to load the new server.

📖 Usage Examples

Network Reconnaissance

"Run a basic nmap scan on 192.168.1.1"
"Perform a stealth nmap scan on my local server"
"Do an aggressive nmap scan on target.local"

Web Application Testing

"Scan example.com with nikto for vulnerabilities"
"Use dirb to find hidden directories on http://testsite.local"
"Check what web technologies are running on myapp.com"

Information Gathering

"Search for Apache 2.4 exploits using searchsploit"
"Run gobuster directory enumeration on http://target.local"
"Perform DNS lookup for domain.com with MX records"

🔧 Tool Reference

nmap_scan(target, scan_type)

• target: IP address or domain name
• scan_type: basic, stealth, version, aggressive

nikto_scan(target, port)

• target: Web server hostname/IP
• port: Port number (default: 80)

dirb_scan(target, wordlist)

• target: Target URL
• wordlist: common, big, small

whatweb_scan(target)

• target: Target URL or hostname

searchsploit_lookup(search_term)

• search_term: Software/service to search exploits for

gobuster_scan(target, mode)

• target: Target URL or domain
• mode: dir, dns, vhost

nslookup_query(domain, query_type)

• domain: Domain name to query
• query_type: A, AAAA, MX, NS, TXT, CNAME, SOA

🏗️ Architecture

Claude Desktop → MCP Protocol → Docker Container → Kali Linux Tools
                                       ↓
                               Input Sanitization & Validation
                                       ↓
                               Secure Tool Execution (pentester user)
                                       ↓
                               Formatted Results & Error Handling

🛡️ Security Considerations

✅ Safe Practices

• Authorized Testing Only - Only scan systems you own or have permission to test
• Controlled Environments - Use test labs and staging environments
• Documentation - Maintain logs of all testing activities
• Responsible Disclosure - Report vulnerabilities through proper channels

❌ Prohibited Uses

• Unauthorized scanning of third-party systems
• Attacking systems without explicit permission
• Using discovered vulnerabilities maliciously
• Violating computer fraud and abuse laws

🔒 Technical Security

• All inputs sanitized to prevent command injection
• Container runs as non-root user with minimal privileges
• Network capabilities restricted to required functions only
• No persistent storage of scan results
• Comprehensive error handling and logging

🧪 Development

Local Testing

# Test the MCP server directly
docker run --rm -i pentest-mcp-server python3 pentest_server.py

# Interactive container for debugging
docker run --rm -it pentest-mcp-server /bin/bash

# Test individual tools
docker run --rm pentest-mcp-server nmap --version

Adding New Tools

1. Install in Dockerfile

   RUN apt-get install -y new-security-tool
   

2. Create wrapper function

   @mcp.tool()
   async def new_tool_scan(target: str = "") -> str:
       """Single-line description of tool functionality."""
       # Implement security pattern here
   

3. Follow security checklist

   • Input sanitization with sanitize_input()
   • Target validation with validate_ip_or_domain()
   • Command construction with argument arrays
   • Timeout protection and error handling

📁 Project Structure

pentest-mcp-server/
├── Dockerfile              # Container configuration
├── requirements.txt         # Python dependencies
├── pentest_server.py       # Main MCP server implementation
├── README.md               # This file
├── CLAUDE.md               # Implementation guidelines
└── readme.txt              # Detailed documentation

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-tool)
3. Follow security guidelines for new tools
4. Add comprehensive tests
5. Update documentation
6. Submit a pull request

📜 License

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

⚠️ Disclaimer

This software is intended for educational purposes and authorized security testing only. Users are solely responsible for ensuring their use complies with applicable laws and regulations. The authors and contributors are not responsible for any misuse or damage caused by this program.

🆘 Support

• Issues: GitHub Issues
• Documentation: Check readme.txt and CLAUDE.md for detailed guides
• Security: For security-related issues, please use responsible disclosure

🏷️ Keywords

penetration-testing cybersecurity mcp-server kali-linux docker nmap nikto ethical-hacking security-tools claude-desktop

⭐ Star this repository if you find it useful for your security research and education!