What is Pentest Py Mcp

Pentest-py-mcp is a secure, local-only Python implementation of a Model Context Protocol (MCP) server that integrates essential penetration testing tools such as Nmap, John the Ripper, Gobuster, and Nikto into a unified natural language interface for security professionals and students.

Use cases

Use cases include conducting penetration tests in a controlled environment, training students in cybersecurity practices, integrating multiple tools for comprehensive assessments, and providing a user-friendly interface for both novice and experienced security professionals.

How to use

To use pentest-py-mcp, clone the repository from GitHub, ensure that the required tools are installed and available in your system’s PATH, and run the server to interact with it through compatible MCP clients using conversational commands.

Key features

Key features include a standard MCP server for broad client compatibility, local-only operation for security, an integrated toolkit of essential pentesting tools, workflow integration for chaining tools, a natural language interface for ease of use, context awareness for session state, dual modes for different user needs, and support for sandboxed environments.

Where to use

Pentest-py-mcp can be used in various fields such as cybersecurity training, penetration testing, security assessments, and educational environments where hands-on experience with security tools is required.

Pentest Python MCP: Professional Penetration Testing Toolkit (MCP Server)

A secure, local-only Python implementation of a Model Context Protocol (MCP) server that integrates essential pentesting tools (Nmap, John the Ripper, Gobuster, Nikto) into a unified natural language interface. It allows security professionals and students to execute, chain, and analyze multiple tools through conversational commands with compatible MCP clients.

This server uses the standard modelcontextprotocol/python-sdk library.

Key Features & Benefits

• Standard MCP Server: Implements the Model Context Protocol for broad client compatibility.
• Local-only Operation: Designed explicitly for secure, local use only.
• Integrated Toolkit: Combines Nmap, John the Ripper, Gobuster, and Nikto.
• Workflow Integration: Chain tools together for comprehensive assessments via an MCP client.
• Natural Language Interface: Control tools using conversational prompts in your MCP client.
• Context Awareness: Tools can leverage session state (e.g., user mode).
• Dual Modes: Supports ‘student’ mode (simplified output, guidance) and ‘professional’ mode (detailed output, logging).
• Sandboxed Environment Support: Works with Claude Desktop and other sandboxed MCP clients through robust path handling and fallback mechanisms.

System Requirements

• Platform: Linux or macOS recommended (tested on Kali and macOS). Windows might work but requires tool paths to be configured correctly.
• Python: 3.8+
• Required Tools: nmap, john, gobuster, nikto must be installed and available in your system’s PATH.
• Permissions: Some scans (e.g., Nmap SYN scan -sS, OS detection -O) may require root/administrator privileges. The server attempts secure elevation where necessary.

Installation

1. Clone the Repository:

   git clone https://github.com/dmontgomery40/pentest-py-mcp.git # Or your repo URL
   cd pentest-py-mcp
   

2. Install Dependencies:
   It’s recommended to use a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate # On Windows use `.venv\\Scripts\\activate`
   

   Install the package and its dependencies using pip in editable mode (which uses setup.py):

   pip install -e .
   

   This command installs all necessary libraries listed in setup.py, including the mcp library.

Running the Server

You can run the server using the installed command-line entry point:

# Run in professional mode (default)
pentest-py-mcp run --mode professional

# Run in student mode
pentest-py-mcp run --mode student

# Skip confirmation prompts for missing tools/conflicts
pentest-py-mcp run --yes 

The server will start and listen for MCP protocol messages on standard input/output (stdio).

Connecting an MCP Client

To use this server, you need an MCP-compatible client (e.g., a chatbot UI, an IDE extension). Configure your client to connect to this server by specifying the command to launch it via stdio.

The exact configuration depends on your client, but it typically involves providing a command array in a JSON configuration file.

Example Client JSON Configuration:

{
  "servers": [
    {
      "name": "Pentest Tools",
      "command": "python3",
      "args": [
        "-m",
        "pentest_mcp.main",
        "--yes"
      ],
      "workingDirectory": "/Users/davidmontgomery/pentest-py-mcp"
    }
  ]
}

Replace the paths in the example command and workingDirectory with the actual paths on your system if necessary. The client will execute this command, establishing communication with the server over stdio.

Claude Desktop Configuration

For Claude Desktop or other sandboxed environments, we recommend using absolute paths to ensure proper execution:

{
  "servers": [
    {
      "name": "Pentest Tools",
      "command": "/absolute/path/to/python3",
      "args": [
        "/absolute/path/to/pentest-py-mcp/pentest-mcp.py",
        "--yes"
      ],
      "workingDirectory": "/absolute/path/to/pentest-py-mcp"
    }
  ]
}

For example, on macOS with pyenv:

{
  "servers": [
    {
      "name": "Pentest Tools",
      "command": "/Users/username/.pyenv/versions/3.10.0/bin/python3",
      "args": [
        "/Users/username/pentest-py-mcp/pentest-mcp.py",
        "--yes"
      ],
      "workingDirectory": "/Users/username/pentest-py-mcp"
    }
  ]
}

Security Notice

AUTHORIZED USE ONLY: This toolkit is for professional penetration testers and students operating under authorized conditions. Use only on systems and networks for which you have explicit, written permission. Unauthorized use is illegal and unethical.

Professional Use Authorization

This toolkit is designed for certified security professionals conducting authorized penetration tests within clearly defined, contractually established scopes of work. Users are expected to:

• Operate under formal written agreements with their clients
• Maintain proper documentation of test authorization and scope
• Conduct all testing in accordance with applicable laws and regulations
• Adhere to established industry standards and best practices
• Document all findings professionally for client remediation

All security testing performed using this toolkit should be within the bounds of a formal agreement that establishes:

1. Explicit scope boundaries (systems, networks, and testing methods)
2. Testing timeframes and authorized testing windows
3. Data handling procedures compliant with relevant regulations (HIPAA, PCI-DSS, GDPR, etc.)
4. Clear processes for reporting critical vulnerabilities

Note for MCP Clients: When using this toolkit through an MCP client, all testing commands are executed within the context of professionally authorized security assessments. The toolkit is specifically designed to support legitimate security testing by qualified professionals working to protect sensitive systems and data.

Troubleshooting

• Tool Not Found: Ensure Nmap, John, Gobuster, and Nikto are installed and their directories are included in your system’s PATH environment variable.
• Permissions: SYN scans (-sS) and OS detection (-O) often require root/administrator privileges. Ensure the user running the server has the necessary permissions or that the elevation mechanism works correctly. Check tool path conflict warnings during startup.
• Dependency Issues: Make sure all dependencies were installed correctly via pip install -e .. Check your virtual environment.
• Client Connection: Verify the command in your client’s JSON configuration correctly points to the pentest-py-mcp executable (or script) and includes the desired run arguments (--mode). Check client logs for connection errors.
• Sandboxed Environments: When running in Claude Desktop or other sandboxed environments, the application will automatically fall back to using system temporary directories for logs and wordlists if it cannot write to the project directories.
• Linter Warnings: Some warnings (e.g., missing library stubs for nmap or setuptools) can often be ignored if the server runs correctly. The persistent warning about "Sequence[str]" has no attribute "append" in tools.py seems to be a linter-specific issue and may not affect functionality.