README.md•4.14 kB
# @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).