intelligent-ears/pd-tools-mcp

ProjectDiscovery MCP Server

A Model Context Protocol (MCP) server that integrates ProjectDiscovery security tools for automated bug bounty reconnaissance and vulnerability scanning.

Features

This MCP server provides comprehensive security reconnaissance capabilities:

Individual Tools

• subfinder - Subdomain discovery using passive sources
• dnsx - DNS resolution and probing
• naabu - Fast port scanning
• httpx - HTTP/HTTPS probing and analysis
• katana - Web crawling and endpoint discovery
• nuclei - Vulnerability scanning with YAML templates

Automated Workflow

• Bug Hunting workflow - End-to-end reconnaissance pipeline that chains all tools together

Workflow Diagram

                    Target Domain
                          │
                          ▼
        ┌─────────────────────────────────────────────┐
        │  Step 1: Subdomain Discovery (subfinder)    │
        │  Find all subdomains via passive sources    │
        └──────────────────┬──────────────────────────┘
                           │
                           ▼
        ┌─────────────────────────────────────────────┐
        │  Step 2: DNS Resolution (dnsx)              │
        │  Resolve domains to IP addresses            │
        └──────────────────┬──────────────────────────┘
                           │
                           ▼
        ┌─────────────────────────────────────────────┐
        │  Step 3: Port Scanning (naabu) [OPTIONAL]   │
        │  Scan top ports on resolved hosts           │
        └──────────────────┬──────────────────────────┘
                           │
                           ▼
        ┌─────────────────────────────────────────────┐
        │  Step 4: HTTP Probing (httpx)               │
        │  Identify live web services                 │
        └──────────────────┬──────────────────────────┘
                           │
                           ▼
        ┌─────────────────────────────────────────────┐
        │  Step 5: Web Crawling (katana) [OPTIONAL]   │
        │  Discover endpoints & paths                 │
        └──────────────────┬──────────────────────────┘
                           │
                           ▼
        ┌─────────────────────────────────────────────┐
        │  Step 6: Vulnerability Scan (nuclei)        │
        │  Test for known vulnerabilities             │
        └──────────────────┬──────────────────────────┘
                           │
                           ▼
                  Comprehensive Report
                  ├─ Attack surface mapping
                  ├─ Open ports & services
                  ├─ Live web applications
                  ├─ Discovered endpoints
                  └─ Security vulnerabilities

Execution Time: ~2 minutes (varies by target size)

Output: JSON report with:

• Total subdomains, resolved hosts, open ports
• Live HTTP services with status codes and titles
• Crawled endpoints and paths
• Vulnerabilities categorized by severity (critical/high/medium/low)

Prerequisites

Before using this MCP server, you must install the ProjectDiscovery tools:

# Install Go (required)
# On Ubuntu/Debian
sudo apt update
sudo apt install golang-go

# On macOS
brew install go

# Install 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/naabu/v2/cmd/naabu@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/katana/cmd/katana@latest
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

# Update Nuclei templates
nuclei -update-templates

# Ensure tools are in PATH
export PATH=$PATH:$(go env GOPATH)/bin

Installation

# Clone the repository
git clone https://github.com/intelligent-ears/pd-tools-mcp
cd pd-tools-mcp

# Install dependencies
npm install

# Build the server
npm run build

Usage

With Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "projectdiscovery": {
      "command": "node",
      "args": ["/absolute/path/to/pdmcp/build/index.js"]
    }
  }
}

With VS Code

Create or update .vscode/mcp.json in your workspace:

{
  "projectdiscovery": {
    "type": "stdio",
    "command": "node",
    "args": ["/absolute/path/to/pdmcp/build/index.js"]
  }
}

Standalone Testing

npm start

Available Tools

1. subfinder

Discover subdomains for a target domain.

Input:

• domain (string, required): Target domain (e.g., "example.com")
• silent (boolean, optional): Show only subdomains in output

Example:

{
  "domain": "example.com",
  "silent": true
}

2. dnsx

Resolve DNS records for domains.

Input:

• domains (array of strings, required): List of domains to resolve
• recordType (string, optional): DNS record type (A, AAAA, CNAME, etc.)

Example:

{
  "domains": ["example.com", "sub.example.com"],
  "recordType": "A"
}

3. naabu

Scan for open ports on hosts.

Input:

• hosts (array of strings, required): List of hosts to scan
• ports (string, optional): Ports to scan (e.g., "80,443" or "1-1000")
• topPorts (number, optional): Scan top N ports

Example:

{
  "hosts": ["example.com"],
  "topPorts": 100
}

4. httpx

Probe HTTP/HTTPS servers.

Input:

• urls (array of strings, required): List of URLs or hosts
• followRedirects (boolean, optional): Follow HTTP redirects
• screenshot (boolean, optional): Take screenshots

Example:

{
  "urls": ["https://example.com"],
  "followRedirects": true
}

5. katana

Crawl websites and discover endpoints.

Input:

• urls (array of strings, required): List of URLs to crawl
• depth (number, optional): Crawl depth (default: 2)
• scope (string, optional): Crawl scope regex pattern

Example:

{
  "urls": ["https://example.com"],
  "depth": 3
}

6. nuclei

Scan for vulnerabilities using templates.

Input:

• targets (array of strings, required): List of targets
• templates (array of strings, optional): Specific templates to use
• severity (array of strings, optional): Filter by severity (critical, high, medium, low, info)

Example:

{
  "targets": ["https://example.com"],
  "severity": ["critical", "high"]
}

7. Bug hunting workflow

Execute complete automated reconnaissance workflow.

Input:

• domain (string, required): Target domain
• portScan (boolean, optional): Include port scanning (default: true)
• crawl (boolean, optional): Include web crawling (default: true)
• vulnerabilityScan (boolean, optional): Include vulnerability scanning (default: true)
• severityFilter (array of strings, optional): Nuclei severity filter

Rate Limiting Options:

• maxCrawlUrls (number, optional): Maximum URLs to crawl (default: 10)
• maxScanUrls (number, optional): Maximum URLs to scan with Nuclei (default: 20)
• maxTopPorts (number, optional): Maximum top ports for Naabu (default: 100)
• batchSize (number, optional): Batch size for DNS/HTTP requests (default: 50)
• delayBetweenBatches (number, optional): Delay in milliseconds between batches (default: 1000)
• crawlDepth (number, optional): Crawl depth for Katana (default: 2)

Example:

{
  "domain": "example.com",
  "portScan": true,
  "crawl": true,
  "vulnerabilityScan": true,
  "severityFilter": ["critical", "high"],
  "maxCrawlUrls": 50,
  "maxScanUrls": 100,
  "maxTopPorts": 200,
  "batchSize": 25,
  "delayBetweenBatches": 2000,
  "crawlDepth": 3
}

Example (Conservative Rate Limiting):

{
  "domain": "example.com",
  "maxCrawlUrls": 5,
  "maxScanUrls": 10,
  "delayBetweenBatches": 5000
}

Workflow Steps:

1. Subdomain Discovery - Find all subdomains
2. DNS Resolution - Resolve subdomains to IPs
3. Port Scanning - Identify open ports (optional)
4. HTTP Probing - Find live web services
5. Web Crawling - Discover endpoints (optional)
6. Vulnerability Scanning - Detect security issues (optional)

Rate Limiting

The bug bounty workflow includes configurable rate limiting to prevent overwhelming target infrastructure and respect responsible disclosure practices.

Rate Limiting Parameters

Usage Examples

Aggressive Scan (use responsibly):

{
  "domain": "example.com",
  "maxCrawlUrls": 100,
  "maxScanUrls": 200,
  "maxTopPorts": 1000,
  "batchSize": 100,
  "delayBetweenBatches": 500,
  "crawlDepth": 3
}

Conservative Scan (recommended for production sites):

{
  "domain": "example.com",
  "maxCrawlUrls": 5,
  "maxScanUrls": 10,
  "maxTopPorts": 50,
  "batchSize": 10,
  "delayBetweenBatches": 5000,
  "crawlDepth": 1
}

Stealth Scan (minimal footprint):

{
  "domain": "example.com",
  "maxCrawlUrls": 3,
  "maxScanUrls": 5,
  "maxTopPorts": 20,
  "batchSize": 5,
  "delayBetweenBatches": 10000,
  "crawlDepth": 1
}

Best Practices

• Start Conservative: Begin with lower limits and increase gradually
• Respect Target Infrastructure: Use appropriate delays to avoid overwhelming servers
• Bug Bounty Programs: Always follow the program's rules of engagement
• Production Systems: Use extended delays and lower batch sizes
• Monitor Logs: Check stderr output for rate limiting status messages

Example Usage

Once configured with an MCP client like Claude Desktop, you can use natural language:

"Use the bug_bounty_workflow tool to scan example.com for vulnerabilities"

"Find all subdomains for hackerone.com using subfinder"

"Scan the top 100 ports on example.com with naabu"

"Crawl https://example.com and find all endpoints with katana"

Development

# Watch mode for development
npm run dev

# Build
npm run build

# Run
npm start

Credits

Built with:

• Model Context Protocol SDK
• ProjectDiscovery Tools

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.