๐ BugBounty MCP Server
A comprehensive Model Context Protocol (MCP) server for bug bounty hunting and web application penetration testing. This tool allows you to perform extensive security testing through natural language conversations with an LLM.
๐ Quick Start
The BugBounty MCP Server is a powerful tool for bug bounty hunting and web application penetration testing. You can start using it via Docker or native installation.
Docker Installation (Recommended)
git clone https://github.com/gokulapap/bugbounty-mcp-server.git
cd bugbounty-mcp-server
cp env.example .env
nano .env
docker-compose up --build -d
docker-compose logs -f bugbounty-mcp
docker-compose down
Native Installation
git clone https://github.com/gokulapap/bugbounty-mcp-server.git
cd bugbounty-mcp-server
chmod +x run.sh
./install.sh
โจ Features
๐ Reconnaissance (13 Tools)
- Subdomain Enumeration: Passive and active subdomain discovery
- DNS Enumeration: Comprehensive DNS record analysis
- WHOIS Lookup: Domain registration and ownership information
- Certificate Transparency: SSL certificate log analysis
- Google Dorking: Automated search engine reconnaissance
- Shodan/Censys Integration: IoT and service discovery
- GitHub Reconnaissance: Code repository analysis
- Archive.org Search: Historical website analysis
- Technology Detection: Web stack fingerprinting
- Social Media Search: OSINT across platforms
- Email Enumeration: Email address discovery
- Reverse DNS: IP to hostname resolution
- WAF Detection: Web Application Firewall identification
๐ Scanning (15 Tools)
- Port Scanning: Comprehensive network port analysis
- Service Enumeration: Detailed service fingerprinting
- Web Directory Scanning: Hidden file/directory discovery
- Web Crawling: Automated website exploration
- Parameter Discovery: Hidden parameter identification
- Subdomain Takeover: Vulnerability detection
- SSL/TLS Analysis: Certificate security assessment
- CMS Scanning: WordPress/Drupal/Joomla analysis
- JavaScript Analysis: Client-side security review
- HTTP Methods Testing: Verb tampering detection
- CORS Analysis: Cross-origin policy testing
- Security Headers: HTTP header security analysis
- Nuclei Integration: Vulnerability template scanning
- Fuzzing: Input validation testing
- API Endpoint Discovery: REST/GraphQL/SOAP analysis
๐ก๏ธ Vulnerability Assessment (15 Tools)
- SQL Injection Testing: Automated SQLi detection
- XSS Testing: Cross-site scripting analysis
- Command Injection: OS command execution testing
- File Inclusion (LFI/RFI): Path traversal analysis
- XXE Testing: XML external entity detection
- SSRF Testing: Server-side request forgery
- IDOR Testing: Insecure direct object reference
- CSRF Testing: Cross-site request forgery
- Authentication Bypass: Login mechanism testing
- Privilege Escalation: Permission boundary testing
- JWT Security: JSON Web Token analysis
- Session Management: Session security assessment
- Race Condition: Concurrency vulnerability testing
- Business Logic: Workflow security analysis
- Deserialization: Unsafe object handling detection
๐ Web Application (10 Tools)
- Access Control Testing: Authorization boundary testing
- Security Misconfiguration: Configuration weakness detection
- Sensitive Data Exposure: Information leakage analysis
- API Security Testing: REST/GraphQL security assessment
- File Upload Security: Upload mechanism testing
- Input Validation: Data sanitization analysis
- Cookie Security: Session cookie analysis
- WebSocket Security: Real-time communication testing
- GraphQL Security: Query language vulnerability testing
- Error Handling Analysis: Information disclosure via errors
๐ง Network Security (10 Tools)
- Network Discovery: Live host identification
- Firewall Detection: Security device identification
- Load Balancer Detection: Traffic distribution analysis
- CDN Detection: Content delivery network analysis
- Proxy Detection: Intermediary service identification
- Routing Analysis: Network path examination
- Bandwidth Testing: Network performance analysis
- Wireless Security: WiFi network assessment
- Network Sniffing: Packet capture and analysis
- Lateral Movement: Internal network exploration
๐ต๏ธ OSINT (10 Tools)
- Person Investigation: Individual background research
- Company Investigation: Corporate intelligence gathering
- Dark Web Monitoring: Hidden service surveillance
- Data Breach Checking: Credential exposure analysis
- Social Media Investigation: Profile analysis across platforms
- Paste Site Monitoring: Leaked information detection
- Code Repository Search: Source code intelligence
- Geolocation Investigation: Physical presence analysis
- Threat Intelligence: IoC analysis and attribution
- Metadata Extraction: Document forensics
โ๏ธ Exploitation (10 Tools)
- Exploit Search: Vulnerability database queries
- Payload Generation: Custom exploit creation
- Privilege Escalation: System access expansion
- Lateral Movement: Network propagation techniques
- Persistence Mechanisms: Backdoor installation methods
- Data Exfiltration: Information extraction techniques
- Credential Dumping: Password harvesting methods
- Anti-Forensics: Evidence elimination techniques
- Evasion Techniques: Security control bypass
- Social Engineering: Human factor exploitation
๐ Reporting (10 Tools)
- Vulnerability Reports: Comprehensive security assessments
- Executive Summaries: Business-focused reporting
- Finding Tracking: Vulnerability lifecycle management
- Metrics Dashboard: Security KPI visualization
- Data Export: Multi-format result export
- Remediation Planning: Prioritized fix roadmaps
- Compliance Mapping: Framework alignment analysis
- Risk Assessment: Business impact evaluation
- Scan Comparison: Historical trend analysis
- Proof of Concept: Exploit documentation
๐ฆ Installation
Prerequisites
- Python 3.10 or higher (Python 3.11+ recommended)
- Git
- Docker (for containerized deployment)
- macOS, Linux, or Windows with WSL
Docker Installation
Quick Docker Start
git clone https://github.com/gokulapap/bugbounty-mcp-server.git
cd bugbounty-mcp-server
cp env.example .env
nano .env
docker-compose up --build -d
docker-compose logs -f bugbounty-mcp
docker-compose down
Manual Docker Commands
docker build -t bugbounty-mcp:latest .
docker run -d \
  --name bugbounty-mcp-server \
  -v $(pwd)/output:/app/output \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/.env:/app/.env:ro \
  bugbounty-mcp:latest
docker logs -f bugbounty-mcp-server
docker exec -it bugbounty-mcp-server /bin/bash
docker stop bugbounty-mcp-server
docker rm bugbounty-mcp-server
Docker Environment Variables
docker run -d \
  --name bugbounty-mcp-server \
  -e SHODAN_API_KEY="your_shodan_key" \
  -e VIRUSTOTAL_API_KEY="your_vt_key" \
  -e GITHUB_TOKEN="your_github_token" \
  -e LOG_LEVEL="INFO" \
  -v $(pwd)/output:/app/output \
  bugbounty-mcp:latest
Native Installation
git clone https://github.com/gokulapap/bugbounty-mcp-server.git
cd bugbounty-mcp-server
chmod +x run.sh
./install.sh
Or for manual installation:
python3 -m venv venv
source venv/bin/activate  
pip install -r requirements.txt
pip install -e .
Install external security tools (optional but recommended):
sudo apt update
sudo apt install nmap masscan nikto dirb sqlmap
brew install nmap masscan nikto dirb sqlmap
go install github.com/projectdiscovery/nuclei/v2/cmd/nuclei@latest
go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install github.com/projectdiscovery/httpx/cmd/httpx@latest
go install github.com/OJ/gobuster/v3@latest
go install github.com/ffuf/ffuf@latest
Configure API keys (optional):
cp env.example .env
nano .env
Download wordlists:
./run.sh download-wordlists
./run.sh download-wordlists --type subdomains
./run.sh download-wordlists --type directories
./run.sh download-wordlists --type parameters
./run.sh download-wordlists --type files
./run.sh download-wordlists --help
Validate configuration:
./run.sh validate-config
๐ป Usage Examples
Starting the MCP Server
Docker Usage (Recommended)
docker-compose up -d
docker-compose logs -f bugbounty-mcp
docker-compose down
Or using Docker directly:
docker run -d \
  --name bugbounty-mcp \
  -v $(pwd)/output:/app/output \
  -v $(pwd)/.env:/app/.env:ro \
  bugbounty-mcp:latest
docker exec bugbounty-mcp bugbounty-mcp validate-config
docker exec bugbounty-mcp bugbounty-mcp list-tools
Native Usage with run.sh
cd bugbounty-mcp-server
./run.sh serve
Command Line Interface
./run.sh --help
./run.sh serve
./run.sh list-tools
./run.sh validate-config
./run.sh quick-scan --target example.com
./run.sh download-wordlists --type subdomains
./run.sh export-config --format yaml
bugbounty-mcp export-config --format yaml -o config.yaml
MCP Server Integration with LLMs
Supported LLM Clients
1. Claude Desktop (Recommended)
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
For Docker (recommended):
{
  "mcpServers": {
    "bugbounty-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "bugbounty-mcp-server", "bugbounty-mcp", "serve"],
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}
For Native Installation:
{
  "mcpServers": {
    "bugbounty-mcp": {
      "command": "/Users/your-username/Documents/bugbounty-mcp-server/run.sh",
      "args": ["serve"],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}
2. VS Code with GitHub Copilot Integration
Prerequisites:
- VS Code with GitHub Copilot extension enabled
- MCP extension for VS Code (if available in marketplace)
Configuration Steps:
For Docker Deployment (Recommended):
docker-compose up --build -d
nc -z localhost 3001 && echo "MCP server is ready"
Then configure VS Code MCP settings:
{
  "mcp.servers": {
    "bugbounty-docker": {
      "command": "nc",
      "args": ["localhost", "3001"],
      "description": "BugBounty MCP Server running in Docker",
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}
Alternative Docker configuration using direct Docker exec:
{
  "mcp.servers": {
    "bugbounty-docker": {
      "command": "docker",
      "args": ["exec", "-i", "bugbounty-mcp-server", "bugbounty-mcp", "serve"],
      "description": "BugBounty MCP Server via Docker exec",
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}
For Native Installation:
{
  "mcp.servers": {
    "bugbounty-native": {
      "command": "/Users/your-username/Documents/bugbounty-mcp-server/run.sh",
      "args": ["serve"],
      "description": "BugBounty MCP Server native installation",
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}
Verify Connection:
- Restart VS Code or reload the MCP extension
- Open the MCP panel in VS Code (if available)
- You should see the BugBounty server connected
- Test by asking GitHub Copilot: "List available security tools from BugBounty MCP"
Troubleshooting Docker Integration:
docker-compose ps
nc -z localhost 3001 || echo "Port 3001 not accessible"
docker-compose logs -f bugbounty-mcp
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}' | nc localhost 3001
3. Custom MCP Clients
import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import stdio_client
async def use_bugbounty_mcp():
    async with stdio_client(["./run.sh", "serve"]) as (read, write):
        async with ClientSession(read, write) as session:
            
            await session.initialize()
            
            
            tools = await session.list_tools()
            print(f"Available tools: {len(tools)}")
            
            
            result = await session.call_tool(
                "subdomain_enumeration",
                {"domain": "example.com", "passive_only": True}
            )
            print(result)
asyncio.run(use_bugbounty_mcp())
4. Integration Examples
./run.sh serve
Example LLM conversation:
User: "Please perform a comprehensive security assessment of example.com"
LLM: I'll help you conduct a comprehensive security assessment using the BugBounty MCP tools. Let me start by gathering information about the target.
[The LLM will automatically use tools like:]
- subdomain_enumeration to find subdomains
- port_scanning to identify open services  
- vulnerability_scanning to detect security issues
- web_directory_scanning to find hidden files
- And 90+ other security tools as needed
Troubleshooting MCP Integration
If the server doesn't start in Claude Desktop:
For Docker deployment:
docker ps | grep bugbounty-mcp
docker logs bugbounty-mcp-server
docker exec bugbounty-mcp-server bugbounty-mcp --help
ls -la /var/run/docker.sock
For Native deployment:
pwd
chmod +x run.sh
./run.sh serve
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/
- Windows: %LOCALAPPDATA%\Claude\logs\
Docker Advanced Usage
Development with Docker
docker build -t bugbounty-mcp:dev --target builder .
docker run -it --rm \
  -v $(pwd):/app \
  -v $(pwd)/output:/app/output \
  bugbounty-mcp:dev bash
docker exec bugbounty-mcp nmap --version
docker exec bugbounty-mcp nuclei -version
docker exec bugbounty-mcp subfinder -version
Performance Tuning
docker run -d \
  --name bugbounty-mcp \
  --cpus="2.0" \
  --memory="4g" \
  -v $(pwd)/output:/app/output \
  bugbounty-mcp:latest
docker stats bugbounty-mcp
Backup and Persistence
docker run --rm \
  -v bugbounty-data:/data \
  -v $(pwd)/backup:/backup \
  alpine tar czf /backup/data-backup-$(date +%Y%m%d).tar.gz -C /data .
docker run --rm \
  -v bugbounty-data:/data \
  -v $(pwd)/backup:/backup \
  alpine tar xzf /backup/data-backup-XXXXXXXX.tar.gz -C /data
Docker Management Script
chmod +x docker.sh
./docker.sh build && ./docker.sh run --api-keys
./docker.sh logs --follow
./docker.sh shell
./docker.sh validate
./docker.sh restart --force
./docker.sh clean --force
./docker.sh backup
./docker.sh restore backup/file.tar.gz
./docker.sh build --dev
./docker.sh run --dev
Example Configuration
api_keys:
  shodan: "your_shodan_api_key"
  virustotal: "your_virustotal_api_key"
  github: "your_github_token"
tools:
  nmap_path: "nmap"
  nuclei_path: "nuclei"
  max_concurrent_scans: 10
  default_timeout: 30
scanning:
  default_ports: ["21", "22", "23", "25", "53", "80", "443", "8080", "8443"]
  max_crawl_depth: 3
  max_pages_to_crawl: 100
output:
  output_dir: "output"
  report_format: "json"
  create_html_report: true
safety:
  safe_mode: true
  allowed_targets: ["*.example.com", "192.168.1.0/24"]
  blocked_targets: ["*.gov", "*.mil"]
๐ฃ๏ธ Natural Language Examples
Reconnaissance
"Perform subdomain enumeration for example.com using both passive and active methods"
"Check if example.com uses a CDN and try to find the origin server"
"Search GitHub for any repositories mentioning example.com that might contain sensitive information"
Vulnerability Testing
"Test the login form at https://example.com/login for SQL injection vulnerabilities"
"Scan https://example.com for XSS vulnerabilities in all input parameters"
"Check if https://example.com has any CORS misconfigurations"
Comprehensive Testing
"Perform a complete security assessment of example.com including:
- Subdomain discovery
- Port scanning
- Web application testing
- SSL/TLS analysis
- Generate a detailed report"
OSINT Gathering
"Investigate the company Example Corp for:
- Employee information
- Technology stack
- Recent data breaches
- Social media presence"
๐ง Configuration
Environment Variables
| Property | Details | Required | 
| SHODAN_API_KEY | Shodan API key for device discovery | No | 
| VIRUSTOTAL_API_KEY | VirusTotal API key for threat intelligence | No | 
| CENSYS_API_ID | Censys API ID for certificate/host search | No | 
| CENSYS_API_SECRET | Censys API secret | No | 
| GITHUB_TOKEN | GitHub token for repository search | No | 
| SECURITYTRAILS_API_KEY | SecurityTrails API for DNS history | No | 
| HUNTER_IO_API_KEY | Hunter.io API for email discovery | No | 
| BINARYEDGE_API_KEY | BinaryEdge API for internet scanning | No | 
Tool Paths
tools:
  nmap_path: "/usr/local/bin/nmap"
  masscan_path: "/opt/masscan/bin/masscan"
  nuclei_path: "/home/user/go/bin/nuclei"
  
Safety Features
safety:
  safe_mode: true                    
  allowed_targets:                   
    - "*.example.com"
    - "192.168.1.0/24"
    - "10.0.0.0/8"
  blocked_targets:                   
    - "*.gov"
    - "*.mil"
    - "*.edu"
  rate_limit_enabled: true          
  requests_per_second: 10.0         
๐ Documentation
The project structure is as follows:
bugbounty-mcp-server/
โโโ bugbounty_mcp_server/
โ   โโโ __init__.py
โ   โโโ server.py              # Main MCP server
โ   โโโ config.py              # Configuration management
โ   โโโ utils.py               # Utility functions
โ   โโโ cli.py                 # Command-line interface
โ   โโโ tools/
โ       โโโ __init__.py
โ       โโโ base.py            # Base tool class
โ       โโโ recon.py           # Reconnaissance tools
โ       โโโ scanning.py        # Scanning tools
โ       โโโ vulnerability.py   # Vulnerability assessment
โ       โโโ webapp.py          # Web application tools
โ       โโโ network.py         # Network security tools
โ       โโโ osint.py           # OSINT tools
โ       โโโ exploitation.py    # Exploitation tools
โ       โโโ reporting.py       # Reporting tools
โโโ wordlists/                 # Wordlists for scanning
โโโ output/                    # Scan results and reports
โโโ data/                      # Persistent data storage
โโโ pyproject.toml             # Project configuration
โโโ README.md                  # This file
โโโ LICENSE                    # MIT License
โโโ SECURITY.md               # Security guidelines
๐ Security Considerations
Responsible Usage
This tool is designed for authorized security testing only. Users must:
- Obtain explicit permission before testing any systems
- Comply with local laws and regulations
- Respect rate limits and avoid DoS conditions
- Follow responsible disclosure for any vulnerabilities found
Safety Features
- Target Whitelisting: Configure allowed targets
- Rate Limiting: Prevent overwhelming target systems
- Safe Mode: Enable additional safety checks
- Logging: Comprehensive audit trails
Legal Disclaimer
Users are solely responsible for ensuring their use of this tool complies with applicable laws and regulations. Gokul (apgokul008@gmail.com) is not responsible for any misuse or damage caused by this software.
๐ค Contributing
We welcome contributions! Please see our Contributing Guidelines for details.
Development Setup
git clone https://github.com/gokulapap/bugbounty-mcp-server.git
cd bugbounty-mcp-server
pip install -e ".[dev]"
pre-commit install
pytest
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Acknowledgments
- OWASP for security testing methodologies
- ProjectDiscovery for excellent security tools
- SecLists for comprehensive wordlists
- The bug bounty and security research community
๐ Support
๐ Roadmap
- [ ] Web-based dashboard
- [ ] Integration with popular bug bounty platforms
- [ ] Machine learning-powered vulnerability detection
- [ ] Collaborative testing features
- [ ] Advanced evasion techniques
- [ ] Mobile application testing tools
- [ ] Cloud security assessment tools
- [ ] Blockchain security testing
โ ๏ธ Important Note
This tool is for authorized security testing only. Unauthorized use against systems you don't own or have explicit permission to test is illegal and unethical.