mcpdns: DNS & Domain Troubleshooting MCP Server

mcpdns is a specialized Model Context Protocol (MCP) server designed to streamline DNS configuration and domain verification tasks directly within your Integrated Development Environment (IDE). Built using the fastmcp framework, it provides a suite of tools to help developers, DevOps engineers, and system administrators quickly diagnose and confirm domain setups without constant context switching.

The primary goal is to simplify common workflows, such as verifying domain configuration when pointing it to services like Replit, Lovable, Vercel, or other hosting platforms.

System Architecture

graph TD
    subgraph "IDE"
        IDE[User in IDE]
        MCP_Client[MCP Client]
    end
    
    subgraph "fastmcp Framework"
        Server[FastMCP Server]
        Router[Tool Router]
        Schema[Schema Validator]
        Auth[Authentication]
    end
    
    subgraph "DNS MCP Implementation"
        subgraph "Controllers"
            C1[DNS Lookup Controller]
            C2[WHOIS Lookup Controller]
            C3[Domain Search Controller]
            C4[MCP Tool Controller]
        end
        
        subgraph "Models"
            M1[DNS Lookup Model]
            M2[WHOIS Lookup Model]
            M3[Provider Manager]
            M4[Cache Manager]
            M5[Domain Search Model]
            M6[TLD Database]
        end
        
        subgraph "Services"
            S1[DNS Service]
            S2[WHOIS Service]
            S3[Cache Service]
            S4[Domain Suggestion Service]
            S5[Domain Availability Service]
            S6[Domain Ranking Service]
        end
    end
    
    IDE --> MCP_Client
    MCP_Client --> Server
    
    Server --> Router
    Router --> Schema
    Router --> Auth
    
    Router --> C4
    C4 --> C1
    C4 --> C2
    C4 --> C3
    
    C1 --> M1
    C2 --> M2
    C3 --> M5
    M1 --> M3
    M1 --> M4
    M2 --> M4
    M5 --> M6
    M5 --> M4
    
    M1 --> S1
    M2 --> S2
    M4 --> S3
    M5 --> S4
    M5 --> S5
    M5 --> S6
    
    M3 --> DNS1[Google DNS]
    M3 --> DNS2[OpenDNS]
    M3 --> DNS3[Cloudflare DNS]

MCP Tools Provided

The mcpdns server provides the following tools through the Model Context Protocol:

DNS Lookup Tool

The DNS lookup tool allows you to query for NS records for a domain, with options to specify which DNS provider to use and whether to use cached results.

Example Input:

{
  "domain": "example.com",
  "provider": "all",
  "useCache": false
}

Example Output:

{
  "domain": "example.com",
  "recordType": "NS",
  "provider": "all",
  "fromCache": false,
  "timestamp": "2025-04-12T20:00:00.000Z",
  "results": [
    {
      "provider": "google",
      "responseTime": 125,
      "records": [
        {
          "name": "example.com",
          "ttl": 86400,
          "value": "a.iana-servers.net"
        },
        {
          "name": "example.com",
          "ttl": 86400,
          "value": "b.iana-servers.net"
        }
      ]
    },
    // Results from other providers...
  ]
}

WHOIS Lookup Tool

The WHOIS lookup tool retrieves domain registration information, including registrar details, creation/expiration dates, and nameservers.

Example Input:

{
  "domain": "example.com",
  "useCache": false,
  "includeRaw": false
}

Example Output:

{
  "domain": "example.com",
  "fromCache": false,
  "timestamp": "2025-04-12T20:00:00.000Z",
  "registrar": {
    "name": "ICANN",
    "url": "https://www.icann.org",
    "ianaId": "376"
  },
  "dates": {
    "created": "1995-08-14T04:00:00Z",
    "updated": "2023-08-14T07:01:33Z",
    "expires": "2025-08-13T04:00:00Z"
  },
  "nameservers": [
    "a.iana-servers.net",
    "b.iana-servers.net"
  ],
  "privacyProtected": false
}

Domain Search Tool

The domain search tool helps find available domain names based on keywords, with options to filter by TLD characteristics and check availability.

Example Input:

{
  "keywords": ["andrew", "hopper", "ai"],
  "maxTldLength": 3,
  "includeDomainHacks": true,
  "checkAvailability": true
}

Example Output:

{
  "query": {
    "keywords": ["andrew", "hopper", "ai"],
    "options": {
      "maxTldLength": 3,
      "includeDomainHacks": true,
      "checkAvailability": true
    }
  },
  "results": [
    {
      "domain": "andrewhopper.ai",
      "tld": "ai",
      "sld": "andrewhopper",
      "available": false,
      "price": {
        "registration": 100,
        "renewal": 100,
        "currency": "USD"
      },
      "relevance": 95,
      "isDomainHack": false
    },
    // More domain suggestions...
  ],
  "domainHacks": [
    // Domain hack suggestions...
  ],
  "stats": {
    "totalResults": 50,
    "availableResults": 20,
    "unavailableResults": 30,
    "notChecked": 0
  }
}

Domain Hack Tool

The domain hack tool finds creative domain names where the TLD forms part of the name (e.g., "artem.is").

Example Input:

{
  "word": "artemis",
  "checkAvailability": true
}

Example Output:

{
  "word": "artemis",
  "results": [
    {
      "domain": "artem.is",
      "tld": "is",
      "sld": "artem",
      "available": false,
      "price": {
        "registration": 50,
        "renewal": 50,
        "currency": "USD"
      },
      "matchQuality": 95,
      "wordCompletion": "artem.is"
    },
    // More domain hack suggestions...
  ],
  "stats": {
    "totalResults": 5,
    "availableResults": 2,
    "unavailableResults": 3,
    "notChecked": 0
  }
}

Key Features & Tools

mcpdns offers a range of granular tools and a high-level verification workflow:

Foundational Tools

• DNS Record Lookups:
  • Query for various record types: NS, A, AAAA, CNAME, TXT.
  • Specify DNS providers (Google, Cloudflare, OpenDNS) or query all simultaneously to compare results and check propagation.
  • View Time-To-Live (TTL) for records.
• WHOIS Lookups:
  • Retrieve essential domain registration data: Registrar, creation/expiration dates, nameservers.
  • Identifies privacy-protected domains.
  • Optionally view raw WHOIS data.
• Network Ping:
  • Check basic network reachability to a domain's resolved IP address.
• HTTP Redirect Checks:
  • Verify if a domain (and its variants like www) correctly redirects to the intended canonical URL.
• SSL Certificate Validation:
  • Check the validity of a domain's SSL certificate, including chain, dates, and hostname matching.
• Caching:
  • Optional caching for DNS and WHOIS results to speed up repeated queries and reduce external load.
  • Supports cache bypass and invalidation.

Service Verification Workflow

• Template-Based Verification: Define templates for common services (e.g., Replit, Lovable, Vercel) specifying the required DNS records (type, value), redirect behavior, and other checks.
• Consolidated Check: Use a single command (e.g., verify example.com for Replit) to run all checks defined in the service template.
• Clear Reporting: Get a summary report indicating pass/fail status for each check in the template, highlighting any issues.

Docker Deployment

The mcpdns server can be easily deployed using Docker. The containerized version includes all necessary DNS utilities (nslookup, whois) and runs on a random port to avoid conflicts with other services.

Prerequisites

• Docker
• Docker Compose (optional, but recommended)

Quick Start

1. Clone the repository:

   git clone https://github.com/andrewhopper/mcpdns.git
   cd mcpdns
   

   Copy

2. Build and start the container:

   docker-compose up -d
   

   Copy

3. Find the assigned port:

   docker-compose ps
   

   Copy

4. Connect your IDE to the MCP server using the displayed port.

Container Configuration

The Docker container includes:

• Node.js runtime for the mcpdns server
• DNS utilities (nslookup, dig, whois)
• Automatic port assignment to avoid conflicts

You can customize the container by modifying the docker-compose.yml file:

version: '3.8'

services:
  mcpdns:
    build: .
    container_name: mcpdns
    ports:
      - "3000"  # Exposes port 3000 on a random host port
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      NODE_ENV: development
      PORT: 3000
    restart: unless-stopped

Manual Docker Commands

If you prefer not to use Docker Compose:

1. Build the image:

   docker build -t mcpdns .
   

   Copy

2. Run the container:

   docker run -d -p 3000 --name mcpdns mcpdns
   

   Copy

3. Find the assigned port:

   docker port mcpdns
   

   Copy

Integration

• MCP Server: Built using the fastmcp framework for standardized communication.
• IDE Integration: Designed to be used within IDEs that support the Model Context Protocol, providing tools via command palettes or potentially dedicated UI panels in the future.

Documentation

For more detailed information on architecture, specific tool implementation, and API schemas, please refer to the documents within the /docs and /.ai directories.

Author

• Andrew Hopper
  • X: x.com/andrewhopper
  • LinkedIn: linkedin.com/in/andrewhopper

License

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

Copyright (c) 2025 Andrew Hopper

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.