MCP Subfinder Server

🚀 MCP Subdomain Discovery Server

An MCP server that encapsulates ProjectDiscovery's subfinder tool, offering powerful subdomain enumeration capabilities via a JSON-RPC API.

🚀 Quick Start

An MCP (Model Context Protocol) server encapsulates ProjectDiscovery's subfinder tool and provides powerful subdomain enumeration capabilities through a JSON-RPC API.

✨ Features

The MCP Subfinder server offers the following features:

1. Subdomain Enumeration: Discover all subdomains of a target domain through multiple data sources.
2. Recursive Scanning: Optional recursive mode for in - depth traversal of subdomains.
3. Filter Configuration: Support for specifying data sources to use or exclude.
4. Timeout Control: Set task timeout to ensure efficiency.

📦 Installation

Install via Binary

# Download and compile the project
git clone https://github.com/copyleftdev/mcp-subfinder.git
cd mcp-subfinder
go build -o mcp-subfinder .

# Start the server
./mcp-subfinder --port=8080

Install via Docker

# Build the Docker image
make docker

# Run the container
make docker-run

💻 Usage Examples

JSON - RPC Interface

Example Request

{
  "jsonrpc": "2.0",
  "method": "enumerateSubdomains",
  "params": {
    "domain": "example.com",
    "timeout": 120,
    "recursive": true,
    "maxDepth": 2,
    "sourcesFilter": ["github", "dnsdumpster"],
    "excludeSourcesFilter": ["waybackarchive"]
  },
  "id": 1
}

Parameter Description

Health Check Interface

curl http://localhost:8080/health

📚 Documentation

Architecture

flowchart LR
    Client([Client]) -->|JSON-RPC| MCP[MCP Server]
    MCP -->|Initialization/Tool List| Client
    MCP -->|Process Request| SF[Subfinder Wrapper]
    SF -->|Configuration| CFG[provider-config.yaml]
    SF -->|Invocation| PD[ProjectDiscovery Subfinder]
    PD -->|Passive Data Sources| API1[Public and Private APIs]
    PD -->|Results| SF
    SF -->|Processed Results| MCP
    MCP -->|JSON Response| Client

Project Structure

• mcp-subfinder.go: The main service file, containing server startup and request - handling logic.
• subdomain_enumerator.go: The core logic for subdomain enumeration, integrating ProjectDiscovery's subfinder tool.
• config.go: The configuration management module, supporting custom settings such as ports and data source filtering.
• Dockerfile: File for building the Docker image.
• Makefile: Project build and run scripts to simplify command - line operations.

📄 License

All the heavy - lifting subdomain enumeration work is done by ProjectDiscovery.

🔗 Contributors

copyleftdev