mcp_subfinder_server

This MCP server wraps ProjectDiscovery's subfinder tool to provide a JSON-RPC API for subdomain enumeration. It exposes an HTTP endpoint at /mcp where clients can initialize, fetch available tools, and invoke the enumerateSubdomains capability with configurable options such as domain, timeout, recursion, and source filtering. The server leverages a provider-config.yaml to supply API keys for premium sources and then runs subfinder accordingly, aggregating results and returning them via JSON-RPC. Use the available tools.list call to inspect capabilities and tools.call with the enumerateSubdomains tool to enumerate subdomains for a domain. The API supports both basic and advanced usage, including recursive discovery and source filtering, with meaningful defaults documented in the repository.

Prerequisites:

• Docker (recommended for the official image) or a Go toolchain if building from source
• Git to clone the repository

Option A - Docker (recommended):

1. Ensure Docker is installed and running.
2. Pull and run the MCP Subfinder Server image: docker run -i copyleftdev/mcp-subfinder-server
3. If needed, map ports or pass environment variables (PORT, PROVIDER_CONFIG) as needed.

Option B - Build from source (Go/Makefile):

1. Install Go (1.20+ recommended) and make:
   • https://golang.org/dl/
2. Clone the repository: git clone https://github.com/copyleftdev/mcp-subfinder-server.git cd mcp-subfinder-server
3. Build the server using the Makefile: make build
4. Run the server (example): PORT=8080 ./bin/mcp-subfinder-server

Note: The README describes a Makefile-driven workflow with commands such as make run, make docker, and make docker-run. Depending on your setup, you may prefer the Makefile workflow to manage environment and deployment.

Tips and common considerations:

• Provide provider-config.yaml to enable premium sources for subfinder; the provider-config.yaml is automatically checked when running with make run.
• The server exposes a JSON-RPC API at http://localhost:8080/mcp; use curl to interact with initialize, tools.list, and tools.call (enumerateSubdomains).
• If running in Docker, you may want to map ports and mount a provider-config.yaml as needed using docker run -p 8080:8080 -v /path/to/config.yaml:/config/provider-config.yaml ... and set PROVIDER_CONFIG=/config/provider-config.yaml.
• The enumerateSubdomains tool supports options like domain, timeout, recursive, maxDepth, sourcesFilter, and excludeSourcesFilter. Adjust these for performance and accuracy.
• Use the make help command to discover additional make targets such as test, integration-test, live-test, and coverage for development workflows.