🐛 mcp-bb

A Model Context Protocol (MCP) server for automated bug bounty workflows.

Quick Start • Features • Tools • Usage • Contributing

What is this?

mcp-bb is a bug bounty workflow server built in Go. It exposes 60+ security tools over the Model Context Protocol so that AI coding assistants (like Gemini in VS Code, Claude, or any MCP-capable client) can run reconnaissance, vulnerability scanning, API testing, mobile app analysis, and reporting — all from a single chat interface.

Think of it as giving your AI assistant actual offensive security superpowers, while keeping everything scoped, rate-limited, and auditable.

Why does this exist?

If you've ever done bug bounty hunting, you know the drill: you juggle dozens of CLI tools, copy-paste targets between terminals, and manually chain tool outputs together. It's tedious.

mcp-bb eliminates that friction. You describe what you want to do in natural language — "enumerate subdomains for example.com and probe for live hosts" — and your AI assistant orchestrates the right tools, in the right order, with the right parameters. You stay in control; the server just handles the boring parts.

✨ Features

Category	Highlights
60+ Security Tools	Subdomain enumeration, port scanning, HTTP probing, nuclei scanning, SQLi/XSS/SSRF/SSTI/XXE/LFI detection, API fuzzing, Android app analysis, Burp Suite integration, and more
Strict Scope Enforcement	Every operation requires an explicit program profile. No accidental out-of-scope testing
Safe Execution	Whitelisted binaries only — no shell injection, no arbitrary command execution
Rate Limiting	Token-bucket rate limiting with per-host controls. Built-in stealth profiles to avoid detection
Concurrency Control	Configurable global and per-host concurrency limits
Artifact Management	Organized output storage with SHA-256 integrity hashing
Audit Logging	Complete JSONL audit trail for every operation
Cross-Platform	Works on Kali Linux, macOS, and Windows

🚀 Quick Start

Prerequisites

Go 1.22+ (for building from source)
An MCP-capable client (VS Code with Gemini Code Assist, Claude Desktop, etc.)

Build & Install

# Clone the repo
git clone https://github.com/metinmcp/mcp-bb.git
cd mcp-bb

# Build
go build -o mcp-bb ./cmd/mcp-bb

# (Linux/macOS) Install system-wide
sudo mv mcp-bb /usr/local/bin/

# (Windows) Build as .exe
go build -o mcp-bb.exe ./cmd/mcp-bb

Or use the Makefile:

make build          # Build for current platform
make build-all      # Build for Linux, macOS, Windows (amd64 + arm64)
make install        # Install to $GOPATH/bin

Verify

mcp-bb --version

🔧 IDE Integration

VS Code (Gemini Code Assist / Copilot)

Add this to your .vscode/mcp.json or user settings.json:

Linux / macOS:

{
  "mcpServers": {
    "bug-bounty": {
      "command": "/usr/local/bin/mcp-bb",
      "args": ["--stdio"]
    }
  }
}

Windows:

{
  "mcpServers": {
    "bug-bounty": {
      "command": "C:\\Users\\YOUR_USERNAME\\.mcp-bb\\bin\\mcp-bb.exe",
      "args": ["--stdio"]
    }
  }
}

Other MCP Clients

Any client that supports MCP stdio transport will work. Just point it at the mcp-bb binary with the --stdio flag.

🛠 Available Tools

Program & Scope (4 tools)

Tool	Description
`bb.program.create`	Create a program profile with scope definitions
`bb.program.list`	List all program profiles
`bb.program.get`	Get details of a specific program
`bb.scope.validate_target`	Check if a target is in scope before testing

Passive Reconnaissance (3)

Tool	Description
`bb.recon.passive.subdomains`	Subdomain enumeration via subfinder
`bb.recon.passive.whois_asn`	WHOIS and ASN lookup
`bb.recon.passive.cert_transparency`	Certificate transparency log search (crt.sh)

Active Reconnaissance (2)

Tool	Description
`bb.recon.active.resolve`	DNS resolution via dnsx
`bb.recon.active.port_scan_light`	Port scanning via nmap

HTTP Tools (3)

Tool	Description
`bb.http.probe`	HTTP probing via httpx
`bb.http.fingerprint`	Technology fingerprinting via whatweb
`bb.http.take_screenshot`	Visual screenshots via gowitness

Content Discovery (3)

Tool	Description
`bb.content.dir_bruteforce`	Directory bruteforce (feroxbuster / ffuf)
`bb.content.crawl`	Web crawling via katana
`bb.content.extract_endpoints`	JavaScript endpoint extraction

Vulnerability Scanning (16) 🔥

Tool	Description
`bb.vuln.nuclei_scan`	Template-based scanning (nuclei)
`bb.vuln.nmap_service_scan`	Service detection + NSE scripts
`bb.vuln.tls_scan`	TLS/SSL configuration analysis
`bb.vuln.sqli_scan`	SQL injection testing (sqlmap)
`bb.vuln.xss_scan`	Cross-site scripting (dalfox)
`bb.vuln.ssrf_scan`	Server-side request forgery
`bb.vuln.lfi_scan`	Local file inclusion / path traversal
`bb.vuln.cors_scan`	CORS misconfiguration detection
`bb.vuln.open_redirect_scan`	Open redirect testing
`bb.vuln.ssti_scan`	Server-side template injection
`bb.vuln.cmdi_scan`	OS command injection
`bb.vuln.xxe_scan`	XML external entity injection
`bb.vuln.subdomain_takeover`	Subdomain takeover checks
`bb.vuln.secrets_scan`	API keys, credentials, tokens
`bb.vuln.header_security`	Security header analysis
`bb.vuln.full_scan`	Comprehensive vulnerability scan

API Testing (9)

Tool	Description
`bb.api.import_openapi`	Import OpenAPI / Swagger specs
`bb.api.generate_requests`	Generate curl / httpie commands
`bb.api.diff_responses`	Response diffing (IDOR detection)
`bb.api.fuzz`	API endpoint fuzzing
`bb.api.broken_auth`	Broken authentication testing
`bb.api.mass_assignment`	Mass assignment detection
`bb.api.rate_limit_test`	Rate limit testing
`bb.api.jwt_analyze`	JWT token analysis
`bb.api.graphql_introspect`	GraphQL introspection

Burp Suite Integration (6)

Tool	Description
`bb.burp.scan`	Launch Burp Suite scans
`bb.burp.scan_status`	Check scan status
`bb.burp.get_issues`	Retrieve discovered issues
`bb.burp.send_to_repeater`	Send requests to Repeater
`bb.burp.sitemap`	Access site map data
`bb.burp.proxy_history`	Browse proxy history

Android Security (12) 📱

Tool	Description
`bb.android.apk_triage`	APK static triage & overview
`bb.android.manifest_audit`	AndroidManifest.xml security audit
`bb.android.component_attack_surface`	Exported component analysis
`bb.android.secret_scan`	Hardcoded secrets detection
`bb.android.frida_bootstrap`	Frida instrumentation setup
`bb.android.runtime_hooks`	Runtime hooking & method tracing
`bb.android.storage_audit`	Insecure data storage checks
`bb.android.network_security_audit`	Network security config analysis
`bb.android.ssl_pinning_assess`	SSL pinning assessment
`bb.android.webview_audit`	WebView security audit
`bb.android.crypto_misuse_scan`	Cryptographic misuse detection
`bb.android.native_surface_audit`	Native library attack surface

Auth Helpers (4)

Tool	Description
`bb.auth.capture_headers`	Save authentication tokens/cookies
`bb.auth.list_profiles`	List saved auth profiles
`bb.auth.rotate_user_agents`	Get rotating user agents
`bb.auth.rate_limit_profiles`	Rate limit recommendations

Reporting (4)

Tool	Description
`bb.report.finding.create`	Create a vulnerability finding
`bb.report.finding.list`	List findings for a program
`bb.report.export_markdown`	Export findings as Markdown
`bb.report.generate`	Generate full professional report

Config & Throttling (4)

Tool	Description
`bb.config.set_rate_limit`	Set requests-per-second limits
`bb.config.set_concurrency`	Set concurrent operation limits
`bb.config.get_throttle_stats`	View throttle statistics
`bb.config.apply_profile`	Apply preset profile (stealth / webapp / api)

Workflow & Environment (3)

Tool	Description
`bb.workflow.run_recon_pipeline`	Full automated recon pipeline
`bb.workflow.start_engagement`	Start a new engagement (guided)
`bb.env.check_dependencies`	Check installed tool dependencies

📖 Usage

Typical Engagement Flow

Once the server is connected to your AI assistant, you can run an entire engagement through natural language:

1. "Create a new program for Target Corp with scope *.target.com"
2. "Apply the stealth profile so we don't trip any rate limits"
3. "Run full recon on target.com — subdomains, DNS, HTTP probing"
4. "Scan the live hosts with nuclei"
5. "Test the login page for SQL injection and XSS"
6. "Generate a report of everything we found"

Behind the scenes, this translates to:

bb.program.create → bb.config.apply_profile → bb.workflow.run_recon_pipeline
→ bb.vuln.nuclei_scan → bb.vuln.sqli_scan + bb.vuln.xss_scan → bb.report.generate

Built-in Prompts

The server ships with guided prompts for common workflows:

Prompt	Description
`start_engagement`	Full engagement setup — from program creation to recon to scanning
`hunt_vulns`	Targeted vulnerability hunting for a specific URL
`run_recon`	Step-by-step reconnaissance pipeline
`test_api`	API endpoint security testing
`triage_findings`	Prioritize and validate scan results
`generate_report`	Professional report generation
`bypass_waf`	WAF bypass strategies for blocked payloads

⚙️ Configuration

Create a config file at ~/.mcp-bb/config.yaml:

programs_dir: ~/.mcp-bb/programs
artifacts_dir: ~/.mcp-bb/artifacts
rate_limits:
  max_rps: 10
  max_concurrency: 5

📦 Installing External Tools

mcp-bb wraps well-known security tools. Install the ones relevant to your workflow:

Kali Linux

# ProjectDiscovery tools
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/dnsx/cmd/dnsx@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install -v github.com/projectdiscovery/katana/cmd/katana@latest

# System packages
sudo apt install -y nmap whatweb whois curl feroxbuster gobuster

# Screenshots
go install -v github.com/sensepost/gowitness@latest

Windows

# Go-based tools (same as Linux)
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest

# Nmap
winget install Nmap.Nmap

macOS

# Go-based tools
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest

# Homebrew packages
brew install nmap whatweb whois feroxbuster

Check which tools are available:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"bb.env.check_dependencies"}}' | mcp-bb --stdio

🏗 Architecture

mcp-bb/
├── cmd/mcp-bb/          # Entry point
├── internal/
│   ├── mcp/             # MCP protocol implementation (JSON-RPC, stdio transport)
│   ├── tools/           # All 60+ tool implementations
│   ├── exec/            # Safe command execution (whitelist-based)
│   ├── programs/        # Program & scope management
│   ├── artifacts/       # Output storage with integrity hashing
│   ├── ratelimit/       # Token-bucket rate limiter
│   └── config/          # Configuration loading
├── configs/             # Default MCP server config
├── Makefile             # Build, test, lint, cross-compile
└── install-*.sh/ps1     # Platform-specific install scripts

🛡 Safety & Ethics

This tool is designed with responsible disclosure in mind:

Authorization first. Every tool requires a program profile with explicit scope definitions. You literally can't test a target without defining it as in-scope first.
Scope validation. Targets are validated before every scan. Out-of-scope requests are rejected.
Rate limiting. Built-in throttling prevents overwhelming targets. Stealth profiles reduce your footprint even further.
Audit trail. Every operation is logged with timestamps, parameters, and results — so you can always prove what you did and when.
No shell injection. Commands are executed via whitelisted binaries with argument-level sanitization. No sh -c anywhere.

⚠️ Only use this tool on targets you have explicit, written authorization to test. Unauthorized testing is illegal and unethical. Always follow your program's rules of engagement.

🤝 Contributing

Contributions are welcome! Whether it's a new tool integration, a bug fix, or documentation improvements — feel free to open an issue or submit a PR.

# Development workflow
make build        # Build the binary
make test         # Run tests with race detection
make lint         # Run linters
make fmt          # Format code
make security     # Run gosec security scan

📄 License

This project is licensed under the MIT License.

Built with ❤️ for the bug bounty community.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.vscode		.vscode
bin		bin
cmd/mcp-bb		cmd/mcp-bb
configs		configs
internal		internal
pkg/types		pkg/types
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
install-kali.sh		install-kali.sh
install-windows.ps1		install-windows.ps1
settings.json.txt		settings.json.txt

Folders and files

Latest commit

History

Repository files navigation

🐛 mcp-bb

What is this?

Why does this exist?

✨ Features

🚀 Quick Start

Prerequisites

Build & Install

Verify

🔧 IDE Integration

VS Code (Gemini Code Assist / Copilot)

Other MCP Clients

🛠 Available Tools

Program & Scope (4 tools)

Passive Reconnaissance (3)

Active Reconnaissance (2)

HTTP Tools (3)

Content Discovery (3)

Vulnerability Scanning (16) 🔥

API Testing (9)

Burp Suite Integration (6)

Android Security (12) 📱

Auth Helpers (4)

Reporting (4)

Config & Throttling (4)

Workflow & Environment (3)

📖 Usage

Typical Engagement Flow

Built-in Prompts

⚙️ Configuration

📦 Installing External Tools

🏗 Architecture

🛡 Safety & Ethics

🤝 Contributing

📄 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages