# ProjectDiscovery MCP Server
A Model Context Protocol (MCP) server that integrates [ProjectDiscovery](https://projectdiscovery.io) 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:
```bash
# 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
```bash
# 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`
```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:
```json
{
"projectdiscovery": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/pdmcp/build/index.js"]
}
}
```
### Standalone Testing
```bash
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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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):**
```json
{
"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
| Parameter | Default | Description |
|-----------|---------|-------------|
| `maxCrawlUrls` | 10 | Maximum number of URLs to crawl with Katana |
| `maxScanUrls` | 20 | Maximum number of URLs to scan with Nuclei |
| `maxTopPorts` | 100 | Maximum number of top ports to scan with Naabu |
| `batchSize` | 50 | Number of items to process in each batch |
| `delayBetweenBatches` | 1000 | Delay in milliseconds between batches |
| `crawlDepth` | 2 | Maximum depth for web crawling |
### Usage Examples
**Aggressive Scan (use responsibly):**
```json
{
"domain": "example.com",
"maxCrawlUrls": 100,
"maxScanUrls": 200,
"maxTopPorts": 1000,
"batchSize": 100,
"delayBetweenBatches": 500,
"crawlDepth": 3
}
```
**Conservative Scan (recommended for production sites):**
```json
{
"domain": "example.com",
"maxCrawlUrls": 5,
"maxScanUrls": 10,
"maxTopPorts": 50,
"batchSize": 10,
"delayBetweenBatches": 5000,
"crawlDepth": 1
}
```
**Stealth Scan (minimal footprint):**
```json
{
"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
```bash
# Watch mode for development
npm run dev
# Build
npm run build
# Run
npm start
```
## Credits
Built with:
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [ProjectDiscovery Tools](https://github.com/projectdiscovery)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
