MCP Subfinder Server

<p align="center"> <img src="assets/logo.png" alt="MCP Subfinder Logo" width="400"> </p>

A Model Context Protocol (MCP) server that wraps ProjectDiscovery's subfinder tool for powerful subdomain enumeration through a JSON-RPC API.

Architecture

flowchart LR
    Client([Client]) -->|JSON-RPC| MCP[MCP Server]
    MCP -->|Initialize/Tools List| Client
    MCP -->|Handles Request| SF[Subfinder Wrapper]
    SF -->|Configuration| CFG[provider-config.yaml]
    SF -->|Calls| PD[ProjectDiscovery Subfinder]
    PD -->|Passive Sources| API1[Public & Private APIs]
    PD -->|Results| SF
    SF -->|Processed Results| MCP
    MCP -->|JSON Response| Client

Credit

All the heavy lifting for subdomain enumeration is done by ProjectDiscovery's subfinder. This project is simply a MCP server wrapper around their excellent tool.

Overview

MCP Subfinder Server provides:

• JSON-RPC API to enumerate subdomains for a given domain
• Support for recursive subdomain discovery
• Source filtering capabilities
• Configurable timeouts and threading
• Detailed logging for troubleshooting

Installation

# Clone the repository
git clone https://github.com/copyleftdev/mcp-subfinder-server.git
cd mcp-subfinder-server

# Build the server using the Makefile
make build

Usage

The server can be run using the Makefile, which provides several helpful commands:

# Run the server on the default port (8080)
make run

# Run the server on a custom port
PORT=9090 make run

# Specify a different provider config file
PROVIDER_CONFIG=my-custom-config.yaml make run

Available Makefile Commands

# Show all available commands
make help

# Run tests
make test

# Run integration tests
make integration-test

# Run live subfinder tests
make live-test

# Generate test coverage report
make coverage

# Format the code
make fmt

# Build for Linux
make build-linux

# Clean the project
make clean

Configuration

For optimal results, add your API keys to the provider-config.yaml file. This allows subfinder to use premium sources for better subdomain discovery.

The provider-config.yaml file is checked automatically when running the server with make run.

API Usage

The server exposes a JSON-RPC API at http://localhost:8080/mcp.

Basic Usage Examples with curl

1. Initialize Connection

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "0.3"
    }
  }'

2. List Available Tools

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools.list"
  }'

3. Basic Subdomain Enumeration

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools.call",
    "params": {
      "name": "enumerateSubdomains",
      "arguments": {
        "domain": "example.com"
      }
    }
  }'

4. Advanced Subdomain Enumeration

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools.call",
    "params": {
      "name": "enumerateSubdomains",
      "arguments": {
        "domain": "example.com",
        "timeout": 120,
        "recursive": true,
        "maxDepth": 2,
        "sourcesFilter": "github,dnsdumpster,alienvault"
      }
    }
  }'

5. Enumeration with Source Exclusion

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools.call",
    "params": {
      "name": "enumerateSubdomains",
      "arguments": {
        "domain": "example.com",
        "timeout": 60,
        "excludeSourcesFilter": "waybackarchive,threatcrowd"
      }
    }
  }'

6. Health Check

curl -X GET http://localhost:8080/health

Available Options

When calling the enumerateSubdomains tool, the following options are available:

Option	Type	Description	Default
domain	string	The domain to enumerate subdomains for (required)	-
timeout	int	Timeout in seconds for the enumeration process	120
recursive	bool	Whether to recursively check discovered subdomains	false
maxDepth	int	Maximum depth for recursive enumeration	2
sourcesFilter	string	Comma-separated list of sources to use	-
excludeSourcesFilter	string	Comma-separated list of sources to exclude	-

Docker Support

The project includes Docker support through the Makefile:

# Build a Docker image
make docker

# Run the server in Docker
make docker-run

# Run with custom port
PORT=9090 make docker-run

Testing

Run tests using the Makefile:

# Run all tests
make test

# Run with test coverage
make coverage

A Postman collection is included in the docs folder for easy testing of all API endpoints.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

copyleftdev