Permutation-Based Domain Analysis MCP Service

This is an MCP endpoint designed to wrap the robust capabilities of dnstwist. It facilitates the systematic generation and interrogation of domain variations to uncover potential typosquatting vectors, identify phishing targets, and surface domains indicative of targeted corporate intelligence gathering. It is engineered for smooth interoperability with MCP-aware clients such as Claude Desktop.

🛑 Cautionary Notice

This utility is intended strictly for authorized cybersecurity auditing and vulnerability research. Adhere strictly to the following: - Validation must only be performed on domains for which explicit testing authorization has been granted. - Always observe established rate limitations and the service policies of target DNS resolvers. - Employ this technology with high ethical standards and full legal compliance. - Be cognizant that excessive automated DNS querying may trigger rate limiting or service blocks from recursive resolvers. - Assess the potential network load impact before initiating extensive scanning operations.

Prerequisites for Local Operation

To run this service environment: - Node.js (version 18 or newer) - Docker containerization platform - An operating environment supporting Docker (macOS, Linux, or Windows with Docker Desktop)

Rapid Deployment Instructions

Installation via Smithery (Recommended for Automated Clients)

Invoke the following command to automatically fetch and configure the DNStwist service through Smithery:

bash npx -y @smithery/cli install @burtthecoder/mcp-dnstwist --client claude

Manual Installation Procedure

1. Secure Docker Installation:
2. For macOS users: Obtain Docker Desktop.

3. For Linux users: Consult the official Docker Engine setup instructions.

4. Install the service executable globally using npm: bash npm install -g mcp-dnstwist

5. Integrate into the Claude Desktop configuration JSON:

{ "mcpServers": { "dnstwist": { "command": "mcp-dnstwist" } } }

Configuration file locations: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Initiate a restart of the Claude Desktop application.

Source Code Execution Alternative

For developers intending to modify or run directly from the source repository:

1. Clone the repository and compile: bash git clone cd mcp-dnstwist npm install npm run build

2. Update the Claude Desktop configuration to point to the compiled entry file:

{ "mcpServers": { "dnstwist": { "command": "node", "args": ["/absolute/path/to/mcp-dnstwist/build/index.js"] } } }

Core Capabilities

• Domain Variant Generation: Creates extensive domain lists utilizing diverse mutation heuristics.
• Registration Status Query: Determines the current registration status of generated domain strings.
• Record Examination: Performs lookups for critical resource records (A, AAAA, MX, NS).
• Web Surface Footprint: Fetches initial HTTP headers to confirm web service presence.
• WHOIS Data Retrieval: Extracts domain creation timestamps and registrar particulars.
• Deception Assessment: Calculates fuzzy hashes for comparing target web content (optional).
• Tunability: Allows customization of recursive DNS endpoints and concurrent processing capacity.
• Output Flexibility: Supports data serialization in JSON, CSV, or simple text list formats.

Service Endpoint: Domain Permutation Analysis

• Endpoint Identifier: fuzz_domain
• Function: Systematically generates and probes domain permutations to discover potential brand squatting, phishing vectors, and impersonation opportunities.
• Arguments:
• domain (Mandatory): The base domain name to subject to analysis (e.g., targetcorp.net).
• nameservers (Optional, Default: "1.1.1.1"): A string listing DNS resolvers, comma-separated.
• threads (Optional, Default: 50): The parallelism level for concurrent DNS lookups.
• format (Optional, Default: "json"): Desired output serialization type (json, csv, list).
• registered_only (Optional, Default: true): Boolean flag to filter results to only those domains that resolve/are registered.
• mxcheck (Optional, Default: true): Flag to initiate MX record verification on resolved domains.
• ssdeep (Optional, Default: false): Activate fuzzy hashing comparison on associated web pages.
• banners (Optional, Default: true): Capture and report HTTP response headers.

Example Payload:

{ "domain": "example.com", "nameservers": "1.1.1.1,8.8.8.8", "threads": 50, "format": "json", "registered_only": true, "mxcheck": true, "banners": true }

Diagnostic & Resolution Guide

Docker Operational Concerns

1. Confirm Docker daemon status: bash docker --version docker ps

2. Investigate user permissions (primarily Linux):

3. Verify the executing user has requisite permissions to interface with the Docker socket.
4. On Linux, consider adding the user to the docker group: sudo usermod -aG docker $USER

General Fault Resolution

1. DNS Resolution Failures:
2. Validate external connectivity to configured DNS servers.
3. Substitute default servers with known stable ones (e.g., 8.8.8.8, 1.0.0.1).

4. Inspect systems for local rate limiting or firewall restrictions.

5. Throughput Constraints:

6. Adjust the threads parameter relative to available system resources and network capacity.

7. Pay attention to observed latency reported by the remote DNS infrastructure.

8. Post-Remediation Steps:

9. Persist any configuration adjustments.
10. Restart the Claude Desktop client to reload the service manifest.

Recognized Service Error Codes

• "Docker is not installed or not running": Action: Ensure Docker Desktop/Engine is active and accessible.
• "Failed to parse dnstwist output": Action: Validate the input domain syntax and confirm expected output format configuration.
• "Error executing dnstwist": Action: Review the underlying container execution logs and user permissions settings.
• "DNS server not responding": Action: Confirm reachability of specified nameservers and test with alternate addresses.

Collaboration Guidelines

1. Create a divergent copy of the repository (Fork).
2. Establish a dedicated feature branch (e.g., git checkout -b enhancement/new-mutation-type).
3. Record modifications (git commit -m 'Implement enhancement XYZ').
4. Push changes to your fork (git push origin enhancement/new-mutation-type).
5. Submit a Merge Request detailing the contribution.

Licensing Status

This software is distributed under the terms of the MIT License (refer to the LICENSE document for specifics).