🧪 Bug Bounty Assistant MCP

An MCP (Model Context Protocol) server that gives an LLM a toolkit of passive and low-impact active reconnaissance tools for authorized bug bounty and security assessment work. The LLM decides which tools to call based on the target and context, then synthesizes findings into a structured report.

⚠️ Authorized use only. This tool is intended strictly for testing assets you own or have explicit written authorization to test (e.g. a program listed on HackerOne/Bugcrowd/Intigriti with the target in scope). Running these tools against systems without permission may violate laws such as the CFAA (US), Computer Misuse Act (UK), or equivalent legislation elsewhere. Always check the program's scope and rules of engagement before scanning.

Features

The server currently exposes the following tools to the calling LLM:

Suggested additional tools (roadmap)

These extend the recon surface while staying passive/low-impact:

Related MCP server: Bug Bounty MCP Server

Architecture

┌─────────────┐        MCP (stdio/HTTP)        ┌──────────────────────┐
│   LLM Host   │ ──────────────────────────────▶│  Bug Bounty MCP      │
│ (Claude, etc)│ ◀──────────────────────────────│  Server              │
└─────────────┘        tool calls/results        └──────────┬───────────┘
                                                              │
                                        ┌─────────────────────┼─────────────────────┐
                                        ▼                     ▼                     ▼
                                 DNS / crt.sh          HTTP(S) client         Headless browser
                                 resolvers             (headers, ssl,        (screenshot,
                                                        robots, sitemap)      JS rendering)

• Transport: stdio (default) or Streamable HTTP, per the MCP spec

• Language: TypeScript (Node.js ≥ 18)

• HTTP client: undici / axios

• Headless browser: playwright (for take_screenshot, JS-rendered find_interesting_endpoints)

• DNS: Node's built-in dns/promises, plus crt.sh queries for subdomain enumeration

• Report output: Markdown by default, optional JSON

Project structure

bug-bounty-mcp/
├── src/
│   ├── index.ts                # MCP server entrypoint, tool registration
│   ├── tools/
│   │   ├── dns.ts
│   │   ├── subdomains.ts
│   │   ├── headers.ts
│   │   ├── cookies.ts
│   │   ├── ssl.ts
│   │   ├── robots.ts
│   │   ├── sitemap.ts
│   │   ├── technologies.ts
│   │   ├── endpoints.ts
│   │   ├── screenshot.ts
│   │   └── report.ts
│   ├── lib/
│   │   ├── http-client.ts      # shared fetch wrapper, timeouts, retries
│   │   ├── rate-limiter.ts     # global politeness/rate-limit control
│   │   ├── scope-guard.ts      # validates target is in an allow-listed scope
│   │   └── logger.ts
│   └── types.ts
├── tests/
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

Installation

Prerequisites

• Node.js ≥ 18

• npm or pnpm

• (Optional) Playwright browsers for screenshots: npx playwright install chromium

Setup

git clone https://github.com/<your-username>/bug-bounty-mcp.git
cd bug-bounty-mcp
npm install
cp .env.example .env
npm run build

Run the server

npm start
# or in dev mode with hot reload
npm run dev

Register with an MCP host (e.g. Claude Desktop / Claude Code)

Add to your MCP config (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "bug-bounty-assistant": {
      "command": "node",
      "args": ["/absolute/path/to/bug-bounty-mcp/dist/index.js"]
    }
  }
}

Configuration

Set these in .env:

# Comma-separated list of domains this server is allowed to scan.
# scope-guard.ts refuses to run tools against anything not listed here.
ALLOWED_SCOPE=example.com,*.example.com

# Requests per second ceiling applied globally (politeness)
MAX_REQUESTS_PER_SECOND=2

# Timeout (ms) for outbound HTTP requests
HTTP_TIMEOUT_MS=10000

# Optional API keys for enrichment tools
SHODAN_API_KEY=
CENSYS_API_ID=
CENSYS_API_SECRET=
GITHUB_TOKEN=

Scope guard: every tool call passes the target through scope-guard.ts, which checks it against ALLOWED_SCOPE and refuses to run if the target isn't explicitly listed. This is the main safety rail — update it per-engagement before you start testing.

Example usage

User: "Analyze example.com for bug bounty recon."

The LLM will typically:

1. Call get_dns_records and find_subdomains to map infrastructure

2. Call check_security_headers, analyze_cookies, and ssl_scan on discovered hosts

3. Call discover_robots / discover_sitemap for structure hints

4. Call detect_technologies to fingerprint the stack

5. Call find_interesting_endpoints to surface API routes worth manual review

6. Call take_screenshot for visual triage across many hosts

7. Call generate_report to produce a single Markdown summary with findings, severity notes, and suggested next manual steps

Sample report output:

# Recon Report — example.com
Generated: 2026-07-10

## DNS
- A: 93.184.216.34
- MX: none found
- NS: a.iana-servers.net, b.iana-servers.net

## Subdomains (4 found)
- www.example.com
- dev.example.com  ⚠ exposed, no auth wall detected
- api.example.com
- mail.example.com

## Security Headers — www.example.com
- CSP: ❌ missing
- HSTS: ✅ present (max-age=63072000)
- X-Frame-Options: ❌ missing

## Recommendations
- Investigate dev.example.com — appears to be a non-production environment reachable externally
- Add CSP and X-Frame-Options headers on the main site

Roadmap

• Add wayback_urls, github_dork_search, check_cname_takeover

• Add per-tool caching to avoid re-hitting the same host repeatedly in one session

• Add a diff_scan tool to compare against a prior report

• Support authenticated scans (session cookie/header injection) for logged-in recon

• Add Slack/Discord webhook output for generate_report

• Docker image for one-command deployment

Contributing

1. Fork the repo and create a feature branch

2. Add or update tools under src/tools/

3. Add tests under tests/

4. Run npm run lint && npm test before opening a PR

Legal

This project performs reconnaissance only — no exploitation, no automated attack payloads, no denial-of-service behavior. It is the user's sole responsibility to:

• Confirm the target is in scope for a bug bounty program or that they have explicit authorization to test it

• Comply with the program's rules of engagement (rate limits, prohibited techniques, disclosure process)

• Comply with local law

The maintainers accept no liability for misuse.

License

MIT