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.

🚀 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

🕵️ 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

📋 Total: 92+ Security Testing Tools

🛠️ Installation

Prerequisites

Python 3.10 or higher (Python 3.11+ recommended)
Git
Docker (for containerized deployment)
macOS, Linux, or Windows with WSL

🐳 Docker Installation (Recommended)

The easiest way to get started is using Docker, which includes all dependencies and security tools pre-installed.

Quick Docker Start

Clone the repository:
git clone https://github.com/gokulapap/bugbounty-mcp-server.git cd bugbounty-mcp-server
Configure API keys (optional but recommended):
# Copy environment template cp env.example .env # Edit .env with your API keys nano .env
Build and run with Docker Compose:
# Build and start the container docker-compose up --build -d # View logs docker-compose logs -f bugbounty-mcp # Stop the container docker-compose down

Manual Docker Commands

# Build the Docker image
docker build -t bugbounty-mcp:latest .

# Run the container
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

# View logs
docker logs -f bugbounty-mcp-server

# Access container shell for debugging
docker exec -it bugbounty-mcp-server /bin/bash

# Stop and remove container
docker stop bugbounty-mcp-server
docker rm bugbounty-mcp-server

Docker Environment Variables

You can pass API keys and configuration directly to Docker:

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

What's Included in Docker Image

The Docker image includes:

✅ Python 3.11 with all required packages
✅ All 20+ security tools (nmap, nuclei, subfinder, httpx, etc.)
✅ Essential wordlists for scanning
✅ Optimized for security and performance
✅ Non-root user for enhanced security
✅ Health checks and monitoring

🔧 Native Installation

Quick Start

Clone the repository:
git clone https://github.com/gokulapap/bugbounty-mcp-server.git cd bugbounty-mcp-server
Run the automated installation:
# Make the run script executable chmod +x run.sh # Install everything automatically ./install.sh
OR for manual installation:
Create virtual environment:
python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
Install dependencies:
pip install -r requirements.txt pip install -e .
Install external security tools (optional but recommended):
# On Ubuntu/Debian sudo apt update sudo apt install nmap masscan nikto dirb sqlmap # On macOS with Homebrew brew install nmap masscan nikto dirb sqlmap # Install Go-based tools 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):
# Copy environment template cp env.example .env # Edit .env file with your API keys nano .env
Download wordlists:
# Download all wordlists (recommended) ./run.sh download-wordlists # Or download specific types ./run.sh download-wordlists --type subdomains ./run.sh download-wordlists --type directories ./run.sh download-wordlists --type parameters ./run.sh download-wordlists --type files # See available options ./run.sh download-wordlists --help
Validate configuration:
./run.sh validate-config

🎯 Usage

Starting the MCP Server

� Docker Usage (Recommended)

Using Docker Compose (easiest):

# Start the server
docker-compose up -d

# View logs in real-time
docker-compose logs -f bugbounty-mcp

# Stop the server
docker-compose down

Using Docker directly:

# Start the server
docker run -d \
  --name bugbounty-mcp \
  -v $(pwd)/output:/app/output \
  -v $(pwd)/.env:/app/.env:ro \
  bugbounty-mcp:latest

# Check server status
docker exec bugbounty-mcp bugbounty-mcp validate-config

# View available tools
docker exec bugbounty-mcp bugbounty-mcp list-tools

🚀 Native Usage with run.sh

The easiest way to start the server natively is using the provided run.sh script:

# Navigate to the project directory
cd bugbounty-mcp-server

# Start the MCP server
./run.sh serve

The script will:

✅ Automatically activate the virtual environment
✅ Load environment variables from .env file
✅ Display server status and available tools
✅ Start the MCP server for LLM integration

📋 Command Line Interface

# List all available commands
./run.sh --help

# Start the MCP server
./run.sh serve

# List all 92+ available tools
./run.sh list-tools

# Validate configuration and tool availability
./run.sh validate-config

# Perform a quick security scan
./run.sh quick-scan --target example.com

# Download security wordlists
./run.sh download-wordlists --type subdomains

# Export configuration template
./run.sh export-config --format yaml
bugbounty-mcp export-config --format yaml -o config.yaml

🤖 MCP Server Integration with LLMs

The BugBounty MCP Server implements the Model Context Protocol (MCP), enabling seamless integration with various LLM applications for natural language penetration testing.

🔗 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

To use the BugBounty MCP Server with VS Code and GitHub Copilot:

Prerequisites:

VS Code with GitHub Copilot extension enabled
MCP extension for VS Code (if available in marketplace)

Configuration Steps:

For Docker Deployment (Recommended):First, ensure your Docker container is running with port 3001 exposed:
# Start the container with automatic MCP server startup docker-compose up --build -d # Verify the server is accessible on port 3001 nc -z localhost 3001 && echo "MCP server is ready"
Then configure VS Code MCP settings by opening VS Code settings (Cmd/Ctrl + ,) and adding:
{ "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:If using the Docker network approach and experiencing issues:
# Check if container is running and healthy docker-compose ps # Test network connectivity nc -z localhost 3001 || echo "Port 3001 not accessible" # Check container logs docker-compose logs -f bugbounty-mcp # Verify MCP server response 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:
            # Initialize the session
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {len(tools)}")
            
            # Call a tool
            result = await session.call_tool(
                "subdomain_enumeration",
                {"domain": "example.com", "passive_only": True}
            )
            print(result)

# Run the client
asyncio.run(use_bugbounty_mcp())

4. Integration Examples

Start the server and test:

# Terminal 1: Start the MCP server
./run.sh serve

# Terminal 2: Test with any MCP client
# The server will be listening on stdio for MCP protocol messages

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:

Ensure Docker container is running:
docker ps | grep bugbounty-mcp # Should show running container
Check container logs:
docker logs bugbounty-mcp-server
Test Docker integration:
docker exec bugbounty-mcp-server bugbounty-mcp --help # Should show help output
Verify Docker socket access (macOS/Linux):
ls -la /var/run/docker.sock # Should be accessible

For Native deployment:

Check the path in your config:
# Get the absolute path pwd # Use this full path in claude_desktop_config.json
Verify the run.sh script is executable:
chmod +x run.sh
Test the server manually:
./run.sh serve # Should show "BugBounty MCP Server started successfully"
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/
- Windows: %LOCALAPPDATA%\Claude\logs\

🐳 Docker Advanced Usage

Development with Docker

# Build development image with debugging tools
docker build -t bugbounty-mcp:dev --target builder .

# Run with volume mounts for live development
docker run -it --rm \
  -v $(pwd):/app \
  -v $(pwd)/output:/app/output \
  bugbounty-mcp:dev bash

# Run specific tools
docker exec bugbounty-mcp nmap --version
docker exec bugbounty-mcp nuclei -version
docker exec bugbounty-mcp subfinder -version

Performance Tuning

# Run with increased resources
docker run -d \
  --name bugbounty-mcp \
  --cpus="2.0" \
  --memory="4g" \
  -v $(pwd)/output:/app/output \
  bugbounty-mcp:latest

# Monitor resource usage
docker stats bugbounty-mcp

Backup and Persistence

# Create data volume backup
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 .

# Restore data volume
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

For easier Docker management, use the included docker.sh script:

# Make executable (first time only)
chmod +x docker.sh

# Build and run in one command
./docker.sh build && ./docker.sh run --api-keys

# Quick operations
./docker.sh logs --follow     # View live logs
./docker.sh shell            # Access container shell
./docker.sh validate         # Validate setup
./docker.sh restart --force  # Force restart
./docker.sh clean --force    # Clean everything

# Data management
./docker.sh backup           # Backup container data
./docker.sh restore backup/file.tar.gz  # Restore data

# Development
./docker.sh build --dev      # Build dev image
./docker.sh run --dev        # Run with source mounting

Example Configuration

# bugbounty_mcp_config.yaml
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

Once integrated with an LLM, you can perform security testing through conversation:

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

Variable	Description	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

The server automatically detects tools in your PATH, but you can specify custom paths:

tools:
  nmap_path: "/usr/local/bin/nmap"
  masscan_path: "/opt/masscan/bin/masscan"
  nuclei_path: "/home/user/go/bin/nuclei"
  # ... other tools

Safety Features

safety:
  safe_mode: true                    # Enable safety checks
  allowed_targets:                   # Whitelist of allowed targets
    - "*.example.com"
    - "192.168.1.0/24"
    - "10.0.0.0/8"
  blocked_targets:                   # Blacklist of forbidden targets
    - "*.gov"
    - "*.mil"
    - "*.edu"
  rate_limit_enabled: true          # Enable rate limiting
  requests_per_second: 10.0         # Request rate limit

📁 Project Structure

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

Clone and install in development mode:
git clone https://github.com/gokulapap/bugbounty-mcp-server.git cd bugbounty-mcp-server pip install -e ".[dev]"
Install pre-commit hooks:
pre-commit install
Run tests:
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

📚 Documentation

RUN_SCRIPT.md - Detailed run.sh script documentation
USAGE.md - Comprehensive usage examples and workflows
SECURITY.md - Security guidelines and best practices
env.example - Environment configuration template

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Security: See SECURITY.md for reporting security issues

🚀 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

⚠️ Warning: 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.

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables comprehensive security testing and penetration testing through natural language conversations with 92+ tools for reconnaissance, vulnerability assessment, web application testing, OSINT, and reporting. Designed for authorized bug bounty hunting and security assessments.