# Directory Structure
```
├── .github
│ └── workflows
│ └── npm-publish.yaml
├── .gitignore
├── Dockerfile
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── smithery.yaml
├── src
│ └── index.ts
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Dependencies
node_modules/
# Build output
build/
# IDE files
.vscode/
.idea/
*.sublime-*
# Logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Environment variables
.env
.env.local
.env.*.local
# Operating System
.DS_Store
Thumbs.db
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# DNStwist MCP Server
[](https://smithery.ai/server/@burtthecoder/mcp-dnstwist)
A Model Context Protocol (MCP) server for [dnstwist](https://github.com/elceef/dnstwist), a powerful DNS fuzzing tool that helps detect typosquatting, phishing, and corporate espionage. This server provides tools for analyzing domain permutations and identifying potentially malicious domains. It is designed to integrate seamlessly with MCP-compatible applications like [Claude Desktop](https://claude.ai).
<a href="https://glama.ai/mcp/servers/it7izu3ufb"><img width="380" height="200" src="https://glama.ai/mcp/servers/it7izu3ufb/badge" alt="mcp-dnstwist MCP server" /></a>
## ⚠️ Warning
This tool is designed for legitimate security research purposes. Please:
- Only analyze domains you own or have permission to test
- Respect rate limits and DNS server policies
- Use responsibly and ethically
- Be aware that some DNS servers may rate-limit or block automated queries
- Consider the impact on DNS infrastructure when running large scans
## Requirements
- Node.js (v18 or later)
- Docker
- macOS, Linux, or Windows with Docker Desktop installed
## Quick Start
### Installing via Smithery
To install DNStwist for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@burtthecoder/mcp-dnstwist):
```bash
npx -y @smithery/cli install @burtthecoder/mcp-dnstwist --client claude
```
### Installing Manually
1. Install Docker:
- macOS: Install [Docker Desktop](https://www.docker.com/products/docker-desktop)
- Linux: Follow the [Docker Engine installation guide](https://docs.docker.com/engine/install/)
2. Install the server globally via npm:
```bash
npm install -g mcp-dnstwist
```
3. Add to your Claude Desktop configuration file:
```json
{
"mcpServers": {
"dnstwist": {
"command": "mcp-dnstwist"
}
}
}
```
Configuration file location:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
4. Restart Claude Desktop
## Alternative Setup (From Source)
If you prefer to run from source or need to modify the code:
1. Clone and build:
```bash
git clone <repository_url>
cd mcp-dnstwist
npm install
npm run build
```
2. Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"dnstwist": {
"command": "node",
"args": ["/absolute/path/to/mcp-dnstwist/build/index.js"]
}
}
}
```
## Features
- **Domain Fuzzing**: Generate domain permutations using various algorithms
- **Registration Check**: Verify if permutated domains are registered
- **DNS Analysis**: Check A, AAAA, MX, and NS records
- **Web Presence**: Capture HTTP banner information
- **WHOIS Data**: Retrieve registration dates and registrar information
- **Phishing Detection**: Generate fuzzy hashes of web pages
- **Configurable**: Custom DNS servers and parallel processing
- **Multiple Formats**: Support for json, csv, and list output formats
## Tools
### Domain Fuzzing Tool
- Name: `fuzz_domain`
- Description: Generate and analyze domain permutations to detect potential typosquatting, phishing, and brand impersonation
- Parameters:
* `domain` (required): Domain name to analyze (e.g., example.com)
* `nameservers` (optional, default: "1.1.1.1"): Comma-separated list of DNS servers
* `threads` (optional, default: 50): Number of threads for parallel processing
* `format` (optional, default: "json"): Output format (json, csv, list)
* `registered_only` (optional, default: true): Show only registered domains
* `mxcheck` (optional, default: true): Check for MX records
* `ssdeep` (optional, default: false): Generate fuzzy hashes of web pages
* `banners` (optional, default: true): Capture HTTP banner information
Example:
```json
{
"domain": "example.com",
"nameservers": "1.1.1.1,8.8.8.8",
"threads": 50,
"format": "json",
"registered_only": true,
"mxcheck": true,
"banners": true
}
```
## Troubleshooting
### Docker Issues
1. Verify Docker is installed and running:
```bash
docker --version
docker ps
```
2. Check Docker permissions:
- Ensure your user has permissions to run Docker commands
- On Linux, add your user to the docker group: `sudo usermod -aG docker $USER`
### Common Issues
1. DNS resolution problems:
- Verify DNS servers are accessible
- Try alternative DNS servers (e.g., 8.8.8.8)
- Check for rate limiting or blocking
2. Performance issues:
- Adjust thread count based on system capabilities
- Consider network bandwidth and latency
- Monitor DNS server response times
3. After fixing any issues:
- Save the configuration file
- Restart Claude Desktop
## Error Messages
- "Docker is not installed or not running": Install Docker and start the Docker daemon
- "Failed to parse dnstwist output": Check if the domain is valid and the format is correct
- "Error executing dnstwist": Check Docker logs and ensure proper permissions
- "DNS server not responding": Verify DNS server accessibility and try alternative servers
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add 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.
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
{
"compilerOptions": {
"target": "ES2020",
"module": "ES2020",
"moduleResolution": "node",
"esModuleInterop": true,
"outDir": "build",
"rootDir": "src",
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "build"]
}
```
--------------------------------------------------------------------------------
/smithery.yaml:
--------------------------------------------------------------------------------
```yaml
# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
startCommand:
type: stdio
configSchema:
# JSON Schema defining the configuration options for the MCP.
type: object
required:
- dockerImage
properties:
dockerImage:
type: string
default: elceef/dnstwist
description: Docker image for DNStwist
commandFunction:
# A function that produces the CLI command to start the MCP on stdio.
|-
(config) => ({ command: 'node', args: ['build/index.js'], env: {} })
```
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
```dockerfile
# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
# Start with a Node.js image
FROM node:18-alpine AS builder
# Set the working directory
WORKDIR /app
# Copy package.json and package-lock.json
COPY package.json package-lock.json ./
# Install dependencies
RUN npm install
# Copy the source code
COPY src ./src
# Copy the tsconfig file
COPY tsconfig.json ./
# Build the TypeScript code
RUN npm run build
# Use a smaller image for runtime
FROM node:18-alpine AS runtime
# Set the working directory
WORKDIR /app
# Copy built files and package.json
COPY --from=builder /app/build ./build
COPY --from=builder /app/package.json ./
# Install only production dependencies
RUN npm install --omit=dev
# Set the command to run the server
ENTRYPOINT ["node", "build/index.js"]
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
{
"name": "@burtthecoder/mcp-dnstwist",
"version": "1.0.4",
"description": "MCP server for dnstwist - DNS fuzzing to detect typosquatting, phishing and corporate espionage",
"main": "build/index.js",
"type": "module",
"bin": {
"mcp-dnstwist": "build/index.js"
},
"files": [
"build",
"README.md",
"LICENSE"
],
"scripts": {
"build": "tsc && chmod +x build/index.js",
"prepublishOnly": "npm run build"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^0.4.0"
},
"devDependencies": {
"@types/node": "^20.0.0",
"typescript": "^5.0.0"
},
"repository": {
"type": "git",
"url": "git+https://github.com/burtthecoder/mcp-dnstwist.git"
},
"keywords": [
"mcp",
"dnstwist",
"dns",
"security",
"phishing",
"typosquatting",
"domain-security",
"claude",
"claude-desktop"
],
"author": "burtmacklin",
"license": "MIT",
"engines": {
"node": ">=18"
}
}
```
--------------------------------------------------------------------------------
/.github/workflows/npm-publish.yaml:
--------------------------------------------------------------------------------
```yaml
name: Publish to NPM
on:
push:
branches:
- main
release:
types: [created]
jobs:
build-and-publish:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
registry-url: 'https://registry.npmjs.org'
- name: Configure Git
run: |
git config --local user.email "[email protected]"
git config --local user.name "GitHub Action"
- name: Install dependencies
run: npm ci
- name: Bump version
if: github.event_name == 'push' && !contains(github.event.head_commit.message, '[skip ci]')
run: |
npm version patch -m "Bump version to %s [skip ci]"
git push
git push --tags
- name: Build
run: npm run build
- name: Publish to NPM
if: success()
run: npm publish --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
CallToolRequestSchema,
ErrorCode,
ListToolsRequestSchema,
McpError,
} from '@modelcontextprotocol/sdk/types.js';
import { exec } from 'child_process';
import { promisify } from 'util';
const execAsync = promisify(exec);
const DOCKER_IMAGE = 'elceef/dnstwist';
interface DnstwistResult {
banner_http?: string;
dns_a?: string[];
dns_aaaa?: string[];
dns_mx?: string[];
dns_ns?: string[];
domain: string;
fuzzer: string;
whois_created?: string;
whois_registrar?: string;
}
interface FuzzDomainArgs {
domain: string;
nameservers?: string;
threads?: number;
format?: 'json' | 'csv' | 'list';
registered_only?: boolean;
mxcheck?: boolean;
ssdeep?: boolean;
banners?: boolean;
}
function isFuzzDomainArgs(args: unknown): args is FuzzDomainArgs {
if (!args || typeof args !== 'object') return false;
const a = args as Record<string, unknown>;
return typeof a.domain === 'string' &&
(a.nameservers === undefined || typeof a.nameservers === 'string') &&
(a.threads === undefined || typeof a.threads === 'number') &&
(a.format === undefined || ['json', 'csv', 'list'].includes(a.format as string)) &&
(a.registered_only === undefined || typeof a.registered_only === 'boolean') &&
(a.mxcheck === undefined || typeof a.mxcheck === 'boolean') &&
(a.ssdeep === undefined || typeof a.ssdeep === 'boolean') &&
(a.banners === undefined || typeof a.banners === 'boolean');
}
class DnstwistServer {
private server: Server;
constructor() {
this.server = new Server({
name: 'dnstwist-server',
version: '0.1.0',
capabilities: {
tools: {}
}
});
this.setupToolHandlers();
this.server.onerror = (error) => console.error('[MCP Error]', error);
process.on('SIGINT', async () => {
await this.server.close();
process.exit(0);
});
// Trigger setup immediately
this.ensureSetup().catch(error => {
console.error('Failed to setup dnstwist:', error);
process.exit(1);
});
}
private async execCommand(command: string): Promise<{ stdout: string; stderr: string }> {
console.error('Executing command:', command);
try {
const result = await execAsync(command, {
maxBuffer: 10 * 1024 * 1024
});
console.error('Command output:', result.stdout);
if (result.stderr) console.error('Command stderr:', result.stderr);
return result;
} catch (error) {
console.error('Command failed:', error);
throw error;
}
}
private async ensureSetup(): Promise<void> {
try {
console.error('Checking Docker...');
try {
await this.execCommand('docker --version');
} catch (error) {
throw new Error('Docker is not installed or not running. Please install Docker and try again.');
}
console.error('Checking if dnstwist image exists...');
try {
await this.execCommand(`docker image inspect ${DOCKER_IMAGE}`);
console.error('Dnstwist image found');
} catch (error) {
console.error('Dnstwist image not found, pulling...');
await this.execCommand(`docker pull ${DOCKER_IMAGE}`);
console.error('Dnstwist image pulled successfully');
}
} catch (error) {
console.error('Setup failed:', error);
throw error;
}
}
private setupToolHandlers() {
this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'fuzz_domain',
description: 'Generate and analyze domain permutations to detect potential typosquatting, phishing, and brand impersonation',
inputSchema: {
type: 'object',
properties: {
domain: {
type: 'string',
description: 'Domain name to analyze (e.g., example.com)'
},
nameservers: {
type: 'string',
description: 'Comma-separated list of DNS servers to use (default: 1.1.1.1)',
default: '1.1.1.1'
},
threads: {
type: 'number',
description: 'Number of threads to use for parallel processing',
minimum: 1,
maximum: 100,
default: 50
},
format: {
type: 'string',
enum: ['json', 'csv', 'list'],
description: 'Output format',
default: 'json'
},
registered_only: {
type: 'boolean',
description: 'Show only registered domain permutations',
default: true
},
mxcheck: {
type: 'boolean',
description: 'Check for MX records',
default: true
},
ssdeep: {
type: 'boolean',
description: 'Generate fuzzy hashes of web pages to detect phishing',
default: false
},
banners: {
type: 'boolean',
description: 'Capture HTTP banner information',
default: true
}
},
required: ['domain']
}
}
]
}));
this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
try {
await this.ensureSetup();
if (request.params.name !== 'fuzz_domain') {
throw new McpError(
ErrorCode.MethodNotFound,
`Unknown tool: ${request.params.name}`
);
}
if (!isFuzzDomainArgs(request.params.arguments)) {
throw new McpError(
ErrorCode.InvalidParams,
'Invalid arguments for fuzz_domain'
);
}
const {
domain,
nameservers = '1.1.1.1',
threads = 50,
format = 'json',
registered_only = true,
mxcheck = true,
ssdeep = false,
banners = true
} = request.params.arguments;
// Build command arguments
const args = [
domain,
'--format', format
];
if (registered_only) args.push('--registered');
if (nameservers) args.push('--nameservers', nameservers);
if (threads) args.push('-t', threads.toString());
if (mxcheck) args.push('--mxcheck');
if (ssdeep) args.push('--ssdeep');
if (banners) args.push('-b');
// Run dnstwist in Docker
const { stdout, stderr } = await this.execCommand(
`docker run --rm ${DOCKER_IMAGE} ${args.join(' ')}`
);
let results: DnstwistResult[];
try {
results = JSON.parse(stdout);
} catch (error) {
throw new Error(`Failed to parse dnstwist output: ${error}`);
}
return {
content: [
{
type: 'text',
text: JSON.stringify(results, null, 2)
}
]
};
} catch (error) {
const errorMessage = error instanceof Error ? error.message : String(error);
return {
content: [
{
type: 'text',
text: `Error executing dnstwist: ${errorMessage}`
}
],
isError: true
};
}
});
}
async run() {
const transport = new StdioServerTransport();
await this.server.connect(transport);
console.error('Dnstwist MCP server running on stdio');
}
}
const server = new DnstwistServer();
server.run().catch(console.error);
```