@joseph.andrade.ii/dns-lookup-mcp/README.md

MCP server for performing DNS lookups with TypeScript

# DNS Lookup MCP Server

A TypeScript-based Model Context Protocol (MCP) server that provides DNS lookup capabilities for AI assistants like Claude.

## Features

- **DNS Lookups**: Query various DNS record types (A, AAAA, CNAME, MX, TXT, NS, PTR, SOA, SRV, CAA)
- **Reverse DNS**: Perform reverse DNS lookups on IP addresses
- **Bulk Resolution**: Resolve all common record types for a hostname at once
- **Custom DNS Servers**: Optionally specify custom DNS servers for queries
- **TypeScript**: Fully typed for better development experience

## Installation

### From npm

```bash
npm install -g @yourusername/dns-lookup-mcp
```

### From Source

```bash
git clone https://github.com/yourusername/dns-lookup-mcp.git
cd dns-lookup-mcp
npm install
npm run build
npm link
```

## Usage with Claude Code CLI

### 1. Configure MCP Settings

Add the DNS lookup server to your Claude Code MCP settings file (`~/.config/claude-code/mcp.json` or appropriate path for your OS):

```json
{
  "mcpServers": {
    "dns-lookup": {
      "command": "npx",
      "args": ["@yourusername/dns-lookup-mcp"]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "dns-lookup": {
      "command": "dns-lookup-mcp"
    }
  }
}
```

### 2. Restart Claude Code

After updating the configuration, restart Claude Code to load the new MCP server.

### 3. Available Tools

The server provides three main tools:

#### `dns_lookup`
Perform DNS lookup for a hostname with specified record type.

Parameters:
- `hostname` (required): The hostname to look up
- `recordType` (optional): DNS record type (A, AAAA, CNAME, MX, TXT, NS, PTR, SOA, SRV, CAA, ANY)
- `timeout` (optional): Query timeout in milliseconds (default: 5000)
- `servers` (optional): Array of custom DNS servers to use

Example usage in Claude:
```
Use the dns_lookup tool to find the A records for example.com
```

#### `reverse_dns`
Perform reverse DNS lookup for an IP address.

Parameters:
- `ip` (required): The IP address to perform reverse lookup on

Example usage in Claude:
```
Use the reverse_dns tool to find the hostname for IP 8.8.8.8
```

#### `dns_resolve_all`
Resolve all common DNS record types for a hostname.

Parameters:
- `hostname` (required): The hostname to resolve all records for

Example usage in Claude:
```
Use the dns_resolve_all tool to get all DNS records for google.com
```

## Development

### Setup

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

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

### Testing Locally

You can test the MCP server locally by running:

```bash
# Run directly with tsx (development)
npm run dev

# Or build and run
npm run build
node dist/index.js
```

The server communicates via stdio, so you'll need an MCP client to interact with it properly.

## Publishing to npm

### 1. Prepare Your Package

1. Update `package.json`:
   - Replace `@yourusername` with your npm username
   - Update author, repository, and homepage URLs
   - Set the appropriate version number

2. Create an npm account if you don't have one:
   ```bash
   npm adduser
   ```

3. Login to npm:
   ```bash
   npm login
   ```

### 2. Publish

```bash
# Build the project
npm run build

# Publish to npm
npm publish --access public
```

### 3. Version Management

To update and publish a new version:

```bash
# Patch version (1.0.0 -> 1.0.1)
npm version patch

# Minor version (1.0.0 -> 1.1.0)
npm version minor

# Major version (1.0.0 -> 2.0.0)
npm version major

# Publish the new version
npm publish
```

## Integration Examples

### Example 1: Using with Claude Code CLI

Once configured, you can ask Claude to perform DNS lookups:

```
User: Can you look up the DNS records for github.com?

Claude: I'll use the DNS lookup tool to check the DNS records for github.com.
[Uses dns_resolve_all tool]
```

### Example 2: Custom Configuration

For advanced users, you can configure the server with environment variables:

```json
{
  "mcpServers": {
    "dns-lookup": {
      "command": "npx",
      "args": ["@yourusername/dns-lookup-mcp"],
      "env": {
        "DNS_TIMEOUT": "10000",
        "DEFAULT_DNS_SERVERS": "8.8.8.8,1.1.1.1"
      }
    }
  }
}
```

## Troubleshooting

### Server Not Starting

1. Check that Node.js version is >= 18.0.0
2. Ensure all dependencies are installed: `npm install`
3. Check the MCP configuration file syntax

### DNS Queries Timing Out

1. Increase the timeout parameter in your queries
2. Check your network connection
3. Try using different DNS servers

### TypeScript Build Errors

1. Ensure TypeScript is installed: `npm install -D typescript`
2. Check that all type definitions are installed
3. Run `npm run clean` and rebuild

## Contributing

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

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

For issues and questions:
- Open an issue on [GitHub](https://github.com/yourusername/dns-lookup-mcp/issues)
- Check the [MCP documentation](https://modelcontextprotocol.io)

## Acknowledgments

- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- Designed for use with [Claude Code CLI](https://github.com/anthropics/claude-code)