cenemil/dns-mcp-server

@cenemiljezweb/dns-mcp-server

A TypeScript-based Model Context Protocol (MCP) server that provides comprehensive DNS lookup capabilities to AI assistants.

Installation

NPM Global Install

npm install -g @cenemiljezweb/dns-mcp-server

NPX (no install needed)

npx @cenemiljezweb/dns-mcp-server

Features

• Multiple DNS Record Types: Support for A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV, and CAA records
• Reverse DNS Lookups: Convert IP addresses back to hostnames
• Batch Queries: Perform multiple DNS lookups in parallel or sequentially
• DNS Trace: Trace the DNS resolution path from root servers to final result
• Configurable DNS Servers: Use custom DNS servers (Google, Cloudflare, or your own)
• Logging: Comprehensive logging with configurable levels
• Error Handling: Robust error handling with detailed error messages

Quick Start

Using with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "dns-server": {
      "command": "npx",
      "args": ["@cenemiljezweb/dns-mcp-server"],
      "env": {}
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "dns-server": {
      "command": "mcp-dns-server",
      "args": [],
      "env": {}
    }
  }
}

Configuration

The server can be configured using a dns-config.json file in your working directory:

{
  "dns": {
    "servers": ["8.8.8.8", "8.8.4.4", "1.1.1.1", "1.0.0.1"],
    "timeout": 5000,
    "retries": 2,
    "useTCP": false
  },
  "cache": {
    "enabled": true,
    "ttl": 300,
    "maxSize": 1000
  },
  "logging": {
    "level": "info",
    "file": "dns-server.log"
  }
}

MCP Tools Available

1. dns_lookup

Perform DNS lookup for a domain to retrieve various record types.

Parameters:

• domain (required): The domain name to lookup
• recordType: Type of DNS record (A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV, CAA)
• useCustomServer: Use custom DNS server if configured
• timeout: Query timeout in milliseconds

Example:

{
  "domain": "example.com",
  "recordType": "A"
}

2. reverse_dns

Perform reverse DNS lookup to find the hostname for an IP address.

Parameters:

• ipAddress (required): The IP address to perform reverse lookup on
• timeout: Query timeout in milliseconds

Example:

{
  "ipAddress": "8.8.8.8"
}

3. batch_dns

Perform multiple DNS lookups in a single operation.

Parameters:

• queries (required): Array of DNS queries to perform
  • domain: Domain name
  • recordTypes: Array of record types to query
• parallel: Execute queries in parallel (default: true)
• timeout: Query timeout per request

Example:

{
  "queries": [
    {"domain": "example.com", "recordTypes": ["A", "MX"]},
    {"domain": "google.com", "recordTypes": ["A", "AAAA"]}
  ],
  "parallel": true
}

4. dns_trace

Trace the DNS resolution path from root servers to the final result.

Parameters:

• domain (required): The domain to trace DNS resolution path
• recordType: The record type to trace (default: A)

Example:

{
  "domain": "example.com",
  "recordType": "A"
}

Development

Local Development

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

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build the project
npm run build

# Run tests
npm test

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Run in development mode with hot reload
• npm start - Run the compiled server
• npm test - Run unit tests
• npm run lint - Run ESLint
• npm run typecheck - Run TypeScript type checking

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Author

MCP DNS Server Contributors

Support

For issues and feature requests, please visit the GitHub repository.