{"id":27023038,"url":"https://github.com/dmontgomery40/pentest-mcp","last_synced_at":"2025-06-10T14:35:27.063Z","repository":{"id":286038672,"uuid":"960171862","full_name":"DMontgomery40/pentest-mcp","owner":"DMontgomery40","description":"NOT for educational purposes: An MCP server for professional penetration testers including nmap, go/dirbuster, nikto, JtR, wordlist building, and more.","archived":false,"fork":false,"pushed_at":"2025-05-06T20:21:50.000Z","size":6767,"stargazers_count":39,"open_issues_count":2,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-02T21:12:54.633Z","etag":null,"topics":["cybersecurity","dirbuster","gobuster","john-the-ripper","jtr","mcp","mcp-server","model-context-protocol","nikto","nmap","pentesting","pentesting-tools","redteam"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DMontgomery40.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-04-04T01:21:50.000Z","updated_at":"2025-06-02T19:52:10.000Z","dependencies_parsed_at":"2025-04-09T18:12:21.656Z","dependency_job_id":null,"html_url":"https://github.com/DMontgomery40/pentest-mcp","commit_stats":null,"previous_names":["dmontgomery40/pentest-mcp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DMontgomery40%2Fpentest-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DMontgomery40%2Fpentest-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DMontgomery40%2Fpentest-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DMontgomery40%2Fpentest-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DMontgomery40","download_url":"https://codeload.github.com/DMontgomery40/pentest-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DMontgomery40%2Fpentest-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":258856694,"owners_count":22768723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cybersecurity","dirbuster","gobuster","john-the-ripper","jtr","mcp","mcp-server","model-context-protocol","nikto","nmap","pentesting","pentesting-tools","redteam"],"created_at":"2025-04-04T20:50:43.311Z","updated_at":"2025-06-10T14:35:27.055Z","avatar_url":"https://github.com/DMontgomery40.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pentest MCP: Professional Penetration Testing Toolkit\n\n[![smithery badge](https://smithery.ai/badge/@DMontgomery40/pentest-mcp)](https://smithery.ai/server/@DMontgomery40/pentest-mcp)\n[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/fa558a10-f45c-4668-9bb6-15630dd51f27)\n\n**Multi-transport MCP server for penetration testing** - works locally via stdio, over the network via HTTP streaming, or with legacy SSE clients. Run it in Docker, deploy it remotely, or use it locally - your choice.\n\n## 🚀 Key Features\n\n### Multi-Transport Architecture\n- **STDIO Transport**: Traditional subprocess communication for local MCP clients\n- **HTTP Streaming Transport**: Modern network protocol with full bidirectional support\n- **SSE Transport**: Legacy compatibility for older MCP clients\n- **One Server, Three Ways to Connect**: Same tools, same interface, your choice of transport\n\n### Professional Pentesting Tools\n- **Network Reconnaissance** with Nmap - full port scanning, service detection, OS fingerprinting\n- **Web Directory Enumeration** with Gobuster - find hidden paths and files\n- **Web Vulnerability Scanning** with Nikto - comprehensive security checks\n- **Password Cracking** with John the Ripper - including custom wordlist generation\n\n### Intelligent Workflow Integration\n- Natural language interface for complex commands\n- Tool chaining for comprehensive assessments\n- Context-aware suggestions for next steps\n- Automated client-ready reporting\n- Voice control compatible (with speech-to-text)\n\n## 🎯 Quick Start\n\n### Install via npm\n```bash\nnpm install -g pentest-mcp\n```\n\n### Install via Smithery\n```bash\nnpx -y @smithery/cli install @DMontgomery40/pentest-mcp --client claude\n```\n\n### Run with your preferred transport\n```bash\n# Local subprocess mode (default)\npentest-mcp\n\n# Network mode with HTTP streaming\nMCP_TRANSPORT=http pentest-mcp\n\n# Legacy SSE mode\nMCP_TRANSPORT=sse pentest-mcp\n```\n\n## 📡 Transport Options\n\n### STDIO (Default) - Local Subprocess\nPerfect for Claude Desktop and local development:\n```json\n{\n  \"servers\": [{\n    \"name\": \"pentest-mcp\",\n    \"command\": \"pentest-mcp\"\n  }]\n}\n```\n\n### HTTP Streaming - Network Mode\nDeploy anywhere, access from anywhere:\n```bash\n# Start server\nMCP_TRANSPORT=http pentest-mcp\n\n# Or with Docker\ndocker run -p 8000:8000 -e MCP_TRANSPORT=http --privileged pentest-mcp:latest\n```\n\nConfigure your client:\n```json\n{\n  \"servers\": [{\n    \"name\": \"pentest-mcp\",\n    \"url\": \"http://localhost:8000/mcp\"\n  }]\n}\n```\n\n### SSE - Legacy Support\nFor backward compatibility with older clients:\n```bash\nMCP_TRANSPORT=sse MCP_SERVER_PORT=8001 pentest-mcp\n```\n\n## 🐳 Docker Deployment\n\n### Simple Docker Run\n```bash\n# STDIO mode (for local MCP clients)\ndocker run -it --rm --privileged pentest-mcp:latest\n\n# HTTP mode (for network access)\ndocker run -p 8000:8000 -e MCP_TRANSPORT=http --privileged pentest-mcp:latest\n```\n\n### Docker Compose with Profiles\n```bash\n# Clone and build\ngit clone https://github.com/dmontgomery40/pentest-mcp.git\ncd pentest-mcp\ndocker-compose build\n\n# Run your preferred transport\ndocker-compose --profile stdio up\ndocker-compose --profile http up\ndocker-compose --profile sse up\n```\n\n### Environment Variables\n- `MCP_TRANSPORT`: Choose transport (stdio, http, sse)\n- `MCP_SERVER_HOST`: Bind address (default: 0.0.0.0)\n- `MCP_SERVER_PORT`: Server port (default: 8000)\n\n## 💬 Usage Examples\n\n### Network Discovery\n```\nSet mode to professional.\nScan 192.168.1.0/24 with SYN scan and service detection.\n```\n\n### Web Application Assessment\n```\nScan 10.0.1.0/24 for web servers.\nFor each web server found, enumerate directories with gobuster using common.txt.\nRun nikto against all discovered web servers.\nCreate a client report summarizing the findings.\n```\n\n### Custom Password Attack\n```\nGenerate a wordlist for company \"Acme Corp\" founded in 1995 by John Smith.\nCrack these hashes using the generated wordlist:\nadmin:$1$xyz$...\nuser:$1$abc$...\n```\n\n## 🔧 System Requirements\n\n- **Tools Required**: nmap, john, gobuster, nikto (must be in PATH)\n- **Node.js**: v16+ for ESM support\n- **Permissions**: Root/admin for SYN scans and OS detection\n- **Platform**: Works on any OS, optimized for Kali Linux\n\n## 📦 Installation Options\n\n### Global Install\n```bash\nnpm install -g pentest-mcp\n```\n\n### Local Development\n```bash\ngit clone https://github.com/dmontgomery40/pentest-mcp.git\ncd pentest-mcp\nnpm install\nnpm run build\n```\n\n### Platform-Specific Tool Installation\n```bash\n# macOS\nbrew install nmap john-jumbo gobuster nikto\n\n# Debian/Ubuntu\nsudo apt update\nsudo apt install nmap john gobuster nikto\n\n# Kali Linux (pre-installed)\n# All tools come pre-installed\n```\n\n## 🛡️ Security \u0026 Legal\n\n**⚠️ AUTHORIZED USE ONLY**: This toolkit is for professional penetration testers operating under valid scope of work. Use only on systems and networks for which you have explicit written authorization.\n\n**🐳 Docker Security Note**: The `--privileged` flag is required for certain scans (SYN, OS detection). Only use in trusted environments or VMs.\n\n## 🔍 Troubleshooting\n\n### Tools Not Found\nEnsure all required tools are in your PATH:\n```bash\nwhich nmap john gobuster nikto\n```\n\n### Permission Denied\nFor SYN scans and OS detection:\n```bash\n# Run with sudo locally\nsudo pentest-mcp\n\n# Or use Docker with --privileged\ndocker run --privileged pentest-mcp:latest\n```\n\n### Build Issues\n```bash\nrm -rf node_modules dist\nnpm install\nnpm run build\n```\n\n### Transport-Specific Issues\n- **HTTP not accessible**: Check firewall rules and port bindings\n- **SSE connection drops**: Ensure keep-alive is enabled\n- **STDIO hangs**: Verify MCP client supports stdio transport\n\n## 📚 Documentation\n\n- [Migration Guide](MIGRATION.md) - Upgrading to v0.5.0\n- [Usage Examples](usage-examples.sh) - Detailed transport examples\n- [Changelog](CHANGELOG.md) - Version history\n\n## 🤝 Contributing\n\nPull requests welcome at the [GitHub repository](https://github.com/dmontgomery40/pentest-mcp). Built for professionals by professionals.\n\n## 📄 License\n\nGPL-3.0-or-later - See LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmontgomery40%2Fpentest-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmontgomery40%2Fpentest-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmontgomery40%2Fpentest-mcp/lists"}