DNS Intel MCP Server

Domain intelligence MCP server providing RDAP lookups, DNS queries, and Certificate Transparency log searches.

Features

• RDAP Lookup: Query domain registration information (registrar, dates, nameservers, status)
• DNS Query: Perform DNS queries for A, AAAA, CNAME, TXT, MX, NS, and SOA records
• CT Search: Search Certificate Transparency logs for certificates issued for a domain

Installation

npm install
npm run build

Usage

As MCP Server (stdio)

# Start the server
npm start

# Or with custom configuration
DNS_RESOLVER=1.1.1.1 npm start

With Claude Desktop

Add to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dns-intel": {
      "command": "node",
      "args": ["/path/to/dns-intel/dist/cli.js"]
    }
  }
}

With HTTP Health Checks

For containerized deployments, enable the HTTP health check server:

npm start -- --http

This exposes:

• GET /health - Health check endpoint
• GET /ready - Readiness probe

Tools

rdap_lookup

Query RDAP for domain registration information.

Input:

{
  "domain": "example.com"
}

Output:

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "registrar": "Example Registrar Inc.",
    "creation_date": "1995-08-14T04:00:00Z",
    "expiration_date": "2025-08-13T04:00:00Z",
    "updated_date": "2024-08-14T07:01:34Z",
    "status": ["clientDeleteProhibited", "clientTransferProhibited"],
    "nameservers": ["a.iana-servers.net", "b.iana-servers.net"]
  },
  "meta": {
    "source": "rdap-bootstrap.iana.org",
    "retrieved_at": "2024-01-15T10:30:00Z"
  }
}

dns_query

Perform DNS queries for various record types.

Input:

{
  "name": "example.com",
  "type": "MX",
  "resolver": "8.8.8.8"
}

Output:

{
  "ok": true,
  "data": {
    "name": "example.com",
    "type": "MX",
    "resolver": "8.8.8.8",
    "records": [
      {
        "name": "example.com",
        "type": "MX",
        "ttl": 300,
        "data": {
          "priority": 10,
          "exchange": "mail.example.com"
        }
      }
    ]
  },
  "meta": {
    "source": "https://dns.google/resolve",
    "retrieved_at": "2024-01-15T10:30:00Z"
  }
}

Supported Record Types:

• A - IPv4 address
• AAAA - IPv6 address
• CNAME - Canonical name
• TXT - Text records
• MX - Mail exchange
• NS - Nameserver
• SOA - Start of authority

ct_search

Search Certificate Transparency logs for certificates.

Input:

{
  "domain": "example.com",
  "limit": 100,
  "cursor": null
}

Output:

{
  "ok": true,
  "data": {
    "domain": "example.com",
    "certificates": [
      {
        "id": 12345678,
        "issuer_ca_id": 16418,
        "issuer_name": "C=US, O=Let's Encrypt, CN=R3",
        "common_name": "*.example.com",
        "name_value": "example.com\n*.example.com",
        "not_before": "2024-01-01T00:00:00",
        "not_after": "2024-04-01T00:00:00",
        "serial_number": "abc123...",
        "entry_timestamp": "2024-01-01T00:00:01"
      }
    ],
    "total_returned": 1
  },
  "meta": {
    "source": "crt.sh",
    "retrieved_at": "2024-01-15T10:30:00Z",
    "pagination": {
      "next_cursor": "eyJvZmZzZXQiOjEwMH0="
    }
  }
}

Configuration

Environment variables:

Variable	Default	Description
DNS_RESOLVER	8.8.8.8	Default DNS resolver for queries
REQUEST_TIMEOUT_MS	10000	Request timeout in milliseconds
HTTP_PORT	3000	HTTP server port for health checks
LOG_LEVEL	info	Log level (debug, info, warn, error)

Response Format

All tools return a standard response envelope:

Success Response

{
  "ok": true,
  "data": { ... },
  "meta": {
    "source": "...",
    "retrieved_at": "2024-01-15T10:30:00Z",
    "pagination": { "next_cursor": null },
    "warnings": []
  }
}

Error Response

{
  "ok": false,
  "error": {
    "code": "UPSTREAM_ERROR",
    "message": "Human readable error message",
    "details": { ... }
  },
  "meta": {
    "retrieved_at": "2024-01-15T10:30:00Z"
  }
}

Error Codes:

• INVALID_INPUT - Invalid input parameters
• UPSTREAM_ERROR - Error from upstream service
• RATE_LIMITED - Rate limit exceeded
• TIMEOUT - Request timed out
• PARSE_ERROR - Failed to parse response
• INTERNAL_ERROR - Internal server error

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Build
npm run build

License

MIT