{"id":26896375,"url":"https://github.com/copyleftdev/mcp_subfinder_server","last_synced_at":"2026-05-03T06:36:35.710Z","repository":{"id":285326683,"uuid":"957743342","full_name":"copyleftdev/mcp_subfinder_server","owner":"copyleftdev","description":" Model Context Protocol (MCP) server that wraps ProjectDiscovery's subfinder tool for powerful subdomain enumeration through a JSON-RPC API.","archived":false,"fork":false,"pushed_at":"2025-03-31T04:16:04.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-31T04:27:00.066Z","etag":null,"topics":["mcp","mcp-server","security","subfinder","t"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/copyleftdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-31T03:40:16.000Z","updated_at":"2025-03-31T04:16:08.000Z","dependencies_parsed_at":"2025-03-31T04:37:30.334Z","dependency_job_id":null,"html_url":"https://github.com/copyleftdev/mcp_subfinder_server","commit_stats":null,"previous_names":["copyleftdev/mcp_subfinder_server"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fmcp_subfinder_server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fmcp_subfinder_server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fmcp_subfinder_server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/copyleftdev%2Fmcp_subfinder_server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/copyleftdev","download_url":"https://codeload.github.com/copyleftdev/mcp_subfinder_server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246580461,"owners_count":20800108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","security","subfinder","t"],"created_at":"2025-04-01T03:43:57.067Z","updated_at":"2026-05-03T06:36:30.691Z","avatar_url":"https://github.com/copyleftdev.png","language":"Go","funding_links":[],"categories":["🔐 Authentication"],"sub_categories":[],"readme":"# MCP Subfinder Server\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"MCP Subfinder Logo\" width=\"400\"\u003e\n\u003c/p\u003e\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8.svg)](https://golang.org/)\n[![MCP Version](https://img.shields.io/badge/MCP-v0.3-success.svg)](https://github.com/copyleftdev/mcp-subfinder-server)\n[![ProjectDiscovery](https://img.shields.io/badge/Powered%20by-ProjectDiscovery-orange.svg)](https://github.com/projectdiscovery/subfinder)\n\nA Model Context Protocol (MCP) server that wraps [ProjectDiscovery's subfinder](https://github.com/projectdiscovery/subfinder) tool for powerful subdomain enumeration through a JSON-RPC API.\n\n## Architecture\n\n```mermaid\nflowchart LR\n    Client([Client]) --\u003e|JSON-RPC| MCP[MCP Server]\n    MCP --\u003e|Initialize/Tools List| Client\n    MCP --\u003e|Handles Request| SF[Subfinder Wrapper]\n    SF --\u003e|Configuration| CFG[provider-config.yaml]\n    SF --\u003e|Calls| PD[ProjectDiscovery Subfinder]\n    PD --\u003e|Passive Sources| API1[Public \u0026 Private APIs]\n    PD --\u003e|Results| SF\n    SF --\u003e|Processed Results| MCP\n    MCP --\u003e|JSON Response| Client\n```\n\n## Credit\n\nAll the heavy lifting for subdomain enumeration is done by [ProjectDiscovery's subfinder](https://github.com/projectdiscovery/subfinder). This project is simply a MCP server wrapper around their excellent tool.\n\n## Overview\n\nMCP Subfinder Server provides:\n\n- JSON-RPC API to enumerate subdomains for a given domain\n- Support for recursive subdomain discovery\n- Source filtering capabilities\n- Configurable timeouts and threading\n- Detailed logging for troubleshooting\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/copyleftdev/mcp-subfinder-server.git\ncd mcp-subfinder-server\n\n# Build the server using the Makefile\nmake build\n```\n\n## Usage\n\nThe server can be run using the Makefile, which provides several helpful commands:\n\n```bash\n# Run the server on the default port (8080)\nmake run\n\n# Run the server on a custom port\nPORT=9090 make run\n\n# Specify a different provider config file\nPROVIDER_CONFIG=my-custom-config.yaml make run\n```\n\n### Available Makefile Commands\n\n```bash\n# Show all available commands\nmake help\n\n# Run tests\nmake test\n\n# Run integration tests\nmake integration-test\n\n# Run live subfinder tests\nmake live-test\n\n# Generate test coverage report\nmake coverage\n\n# Format the code\nmake fmt\n\n# Build for Linux\nmake build-linux\n\n# Clean the project\nmake clean\n```\n\n## Configuration\n\nFor optimal results, add your API keys to the `provider-config.yaml` file. This allows subfinder to use premium sources for better subdomain discovery.\n\nThe provider-config.yaml file is checked automatically when running the server with `make run`.\n\n## API Usage\n\nThe server exposes a JSON-RPC API at `http://localhost:8080/mcp`.\n\n### Basic Usage Examples with curl\n\n#### 1. Initialize Connection\n\n```bash\ncurl -X POST http://localhost:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"initialize\",\n    \"params\": {\n      \"protocolVersion\": \"0.3\"\n    }\n  }'\n```\n\n#### 2. List Available Tools\n\n```bash\ncurl -X POST http://localhost:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 2,\n    \"method\": \"tools.list\"\n  }'\n```\n\n#### 3. Basic Subdomain Enumeration\n\n```bash\ncurl -X POST http://localhost:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 3,\n    \"method\": \"tools.call\",\n    \"params\": {\n      \"name\": \"enumerateSubdomains\",\n      \"arguments\": {\n        \"domain\": \"example.com\"\n      }\n    }\n  }'\n```\n\n#### 4. Advanced Subdomain Enumeration\n\n```bash\ncurl -X POST http://localhost:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 4,\n    \"method\": \"tools.call\",\n    \"params\": {\n      \"name\": \"enumerateSubdomains\",\n      \"arguments\": {\n        \"domain\": \"example.com\",\n        \"timeout\": 120,\n        \"recursive\": true,\n        \"maxDepth\": 2,\n        \"sourcesFilter\": \"github,dnsdumpster,alienvault\"\n      }\n    }\n  }'\n```\n\n#### 5. Enumeration with Source Exclusion\n\n```bash\ncurl -X POST http://localhost:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 5,\n    \"method\": \"tools.call\",\n    \"params\": {\n      \"name\": \"enumerateSubdomains\",\n      \"arguments\": {\n        \"domain\": \"example.com\",\n        \"timeout\": 60,\n        \"excludeSourcesFilter\": \"waybackarchive,threatcrowd\"\n      }\n    }\n  }'\n```\n\n#### 6. Health Check\n\n```bash\ncurl -X GET http://localhost:8080/health\n```\n\n## Available Options\n\nWhen calling the `enumerateSubdomains` tool, the following options are available:\n\n| Option | Type | Description | Default |\n|--------|------|-------------|---------|\n| domain | string | The domain to enumerate subdomains for (required) | - |\n| timeout | int | Timeout in seconds for the enumeration process | 120 |\n| recursive | bool | Whether to recursively check discovered subdomains | false |\n| maxDepth | int | Maximum depth for recursive enumeration | 2 |\n| sourcesFilter | string | Comma-separated list of sources to use | - |\n| excludeSourcesFilter | string | Comma-separated list of sources to exclude | - |\n\n## Docker Support\n\nThe project includes Docker support through the Makefile:\n\n```bash\n# Build a Docker image\nmake docker\n\n# Run the server in Docker\nmake docker-run\n\n# Run with custom port\nPORT=9090 make docker-run\n```\n\n## Testing\n\nRun tests using the Makefile:\n\n```bash\n# Run all tests\nmake test\n\n# Run with test coverage\nmake coverage\n```\n\nA Postman collection is included in the `docs` folder for easy testing of all API endpoints.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Author\n\n[copyleftdev](https://github.com/copyleftdev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcopyleftdev%2Fmcp_subfinder_server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcopyleftdev%2Fmcp_subfinder_server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcopyleftdev%2Fmcp_subfinder_server/lists"}