# @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
```bash
npm install -g @cenemiljezweb/dns-mcp-server
```

### NPX (no install needed)
```bash
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):

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

Or if installed globally:

```json
{
  "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:

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "domain": "example.com",
  "recordType": "A"
}
```

## Development

### Local Development

```bash
# 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](https://github.com/yourusername/mcp-dns-server/issues).