Repository avatar
AI Tools
v2.1.0
active

whoisfreaks-mcp-server

io.github.WhoisFreaks/whoisfreaks-mcp-server

WHOIS, DNS, IP geolocation, SSL and domain intelligence from the WhoisFreaks API.

Documentation

WhoisFreaks MCP Server

A Model Context Protocol (MCP) server that exposes the full WhoisFreaks API suite as AI-callable tools. Works with Claude Desktop, Cursor, Windsurf, VS Code, Continue, Zed, and any other MCP-compatible AI client.

Three ways to use it — pick what fits your setup:

MethodRequiresBest for
⭐ EasiestHosted serverJust your API keyEveryone — nothing to install
Docker (pre-built image)DockerRunning it on your own machine or VM
Build from sourceJava 17 + MavenContributors / custom builds

Connect it to any MCP client via Streamable HTTP (/mcp endpoint, hosted or self-hosted) or stdio (local).

Every user brings their own WhoisFreaks API key — the HTTP server stores no key of its own and uses the key sent with each request.


Table of Contents

  1. Tools Reference (22 tools)
  2. Hosted Server (no install)
  3. Quick Start
  4. Prerequisites
  5. Platform Integration
  6. Example Prompts
  7. Troubleshooting

Tools Reference

WHOIS Tools

ToolDescription
liveWhoisLookupReal-time WHOIS data for any domain — registrar, registrant, dates, nameservers
bulkWhoisLookupReal-time WHOIS data for up to 100 domains in one request
whoisHistoryComplete ownership history timeline for a domain
reverseWhoisLookupFind all domains registered by an email address, owner name or company, or whose name contains a keyword

IP & ASN WHOIS Tools

ToolDescription
ipWhoisLookupWHOIS registration data for any IPv4 or IPv6 address
asnWhoisLookupWHOIS data for an Autonomous System Number (e.g. AS15169)

DNS Tools

ToolDescription
dnsLookupLive DNS records — A, AAAA, MX, NS, CNAME, SOA, TXT, SPF, or all — and PTR records for an IP
bulkDnsLookupLive DNS records for up to 100 domains and 100 IPs in one request
dnsHistoryHistorical DNS records with full change timeline
reverseDnsLookupFind all domains pointing to a given IP or range, mail server or nameserver

IP Intelligence Tools

ToolDescription
ipGeolocationCountry, city, region, ISP, and coordinates for any IP address
bulkIpGeolocationGeolocation for up to 100 IP addresses in one request
ipSecurityIP reputation: VPN, proxy, Tor exit node, relay, bot, spam and known-attacker signals
bulkIpSecurityIP reputation for up to 100 IP addresses in one request

Domain Tools

ToolDescription
domainAvailabilityCheck if a domain is available to register, with optional suggestions
bulkDomainAvailabilityCheck up to 100 domains, or one name across up to 100 extensions (TLDs)
subdomainLookupEnumerate all known subdomains for a domain, with status and date filters
domainDiscoveryFind registered domains that are typo variants of a brand (typosquatting), by keyword or wildcard pattern
subdomainTyposquattingFind subdomains on any domain that contain a typo variant of a brand, such as login.paypa1.example.com
domainReputationRisk verdict, trust score, DGA analysis, threat-feed matches and email security for a domain

SSL Tools

ToolDescription
sslLookupSSL/TLS certificate details — issuer, expiry, SANs, chain, and raw output

Account Tools

ToolDescription
apiKeyUsageCredits and subscription requests used by your API key (costs nothing)

The API's key rotation endpoint has no tool on purpose: it would replace the key the MCP client uses and hand the new one to the AI. Rotate keys in the billing dashboard.

The tools call the endpoints of the WhoisFreaks OpenAPI spec and cost the same credits as calling the API directly; the credit usage page lists them. Bulk tools cost credits for each item.


Hosted Server (no install)

Point any MCP client that supports remote servers at:

https://mcp.whoisfreaks.com

(https://mcp.whoisfreaks.com/mcp is the same endpoint, for clients or configs that expect that path)

and send your WhoisFreaks API key (get one free) in one of these ways:

MethodExampleUse with
Authorization headerAuthorization: Bearer YOUR_API_KEYClaude Code, Cursor, VS Code, Windsurf, Continue
X-API-Key headerX-API-Key: YOUR_API_KEYAny client that supports custom headers
Query parameterhttps://mcp.whoisfreaks.com/?apiKey=YOUR_API_KEYClients without custom headers (claude.ai / Claude Desktop custom connectors)

Prefer a header when your client supports one — URLs with keys can end up in logs and history.

Claude Code

claude mcp add --transport http whoisfreaks https://mcp.whoisfreaks.com \
  --header "Authorization: Bearer YOUR_API_KEY"

claude.ai / Claude Desktop — Settings → Connectors → Add custom connector, URL:

https://mcp.whoisfreaks.com/?apiKey=YOUR_API_KEY

Cursor (~/.cursor/mcp.json), Windsurf, and other JSON-configured clients:

{
  "mcpServers": {
    "whoisfreaks": {
      "url": "https://mcp.whoisfreaks.com",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "whoisfreaks": {
      "type": "http",
      "url": "https://mcp.whoisfreaks.com",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Without a key the server still connects and lists its tools, but every tool call returns an error explaining how to add one. API usage is billed to the key you send.


Quick Start

⭐ Recommended — Docker

No Java or Maven required. Pull the pre-built image directly from Docker Hub and run.

The container runs the same multi-user HTTP server as the hosted one: it needs no API key of its own — clients send theirs with each request (see Hosted Server for the ways to send it). Get a free key at billing.whoisfreaks.com/signup.


Option 1 — Direct docker run (simplest)

docker run -d \
  --name whoisfreaks-mcp \
  --restart unless-stopped \
  -p 3100:3100 \
  whoisfreaks/mcp-server:latest

The MCP server is now live at http://localhost:3100/mcp.


Option 2 — Docker Compose (recommended for production / VM)

Create a docker-compose.yml:

services:
  whoisfreaks-mcp:
    image: whoisfreaks/mcp-server:latest
    container_name: whoisfreaks-mcp
    restart: unless-stopped
    ports:
      - "3100:3100"

Start it:

docker compose up -d

Serving it publicly (HTTPS)

Put a reverse proxy with TLS in front of port 3100. Caddy example (Caddyfile), which obtains a certificate automatically:

mcp.example.com {
    reverse_proxy localhost:3100
}

Nginx example:

location / {
    proxy_pass http://127.0.0.1:3100;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_buffering off;          # stream responses as they are produced
    proxy_read_timeout 300s;      # some WHOIS lookups are slow
}

The server is stateless (no MCP sessions), so you can run several containers behind a load balancer without sticky sessions.

To set up a machine and deploy to it without Docker (nginx, HTTPS, rate limiting, rollback), see ansible/.


Verify Docker is working

# Container should show as "Up"
docker ps

# Health check
curl http://localhost:3100/health
# → {"status":"ok"}

# List all 22 registered tools (any key works for listing; tool calls need a valid one)
curl -s http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-api-key-here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Use with Claude Desktop (Docker stdio mode)

To run the server locally over stdio instead of HTTP, override the Docker entrypoint and pass your key as an environment variable:

{
  "mcpServers": {
    "whoisfreaks": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "WHOISFREAKS_API_KEY=your-api-key-here",
        "--entrypoint", "java",
        "whoisfreaks/mcp-server:latest",
        "-jar", "app.jar"
      ]
    }
  }
}

No port mapping needed here — Claude Desktop talks to the container directly via stdio.


Build from Source

Only needed if you want to modify the code or build a custom version.

Prerequisites:

RequirementMinimum VersionNotes
Java (JDK)17Check with java -version
Maven3.8Check with mvn -version
WhoisFreaks API Key—Get yours at billing.whoisfreaks.com/signup

Clone and build:

git clone https://github.com/whoisfreaks/whoisfreaks-mcp-server.git
cd whoisfreaks-mcp-server
mvn clean package -q

This produces a single self-contained fat JAR:

target/whoisfreaks-mcp-server-2.1.0.jar

Tip: Note the absolute path to this JAR — you will need it in the platform configs below. Example: /Users/yourname/whoisfreaks-mcp-server/target/whoisfreaks-mcp-server-2.1.0.jar


Prerequisites

RequirementNotes
DockerRequired for the recommended Docker path
Java 17 + Maven 3.8Required only if building from source
WhoisFreaks API KeyFree at billing.whoisfreaks.com/signup

Platform Integration

1. Claude Desktop

The simplest setup is the hosted server as a custom connector (Settings → Connectors → Add custom connector). To run it locally instead, Claude Desktop launches the MCP server as a subprocess via stdio using claude_desktop_config.json:

Config file location:

OSPath
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json

⭐ Option A — Docker (recommended, no Java needed)

{
  "mcpServers": {
    "whoisfreaks": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "WHOISFREAKS_API_KEY=your-api-key-here",
        "--entrypoint", "java",
        "whoisfreaks/mcp-server:latest",
        "-jar", "app.jar"
      ]
    }
  }
}

Docker must be running before you open Claude Desktop. The image is pulled automatically on first use.


Option B — JAR directly (requires Java 17)

{
  "mcpServers": {
    "whoisfreaks": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/whoisfreaks-mcp-server-2.1.0.jar"],
      "env": {
        "WHOISFREAKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Steps (both options):

  1. Paste the config above into the config file (create it if it doesn't exist)
  2. Save the file
  3. Quit Claude Desktop completely (Cmd+Q on macOS / taskbar exit on Windows)
  4. Reopen Claude Desktop
  5. Click the hammer icon (Tools) in the chat input — you should see 22 WhoisFreaks tools listed

Verify it works: Type Who owns google.com? and Claude will automatically call liveWhoisLookup.


2. Cursor IDE

Cursor supports both remote (HTTP) and stdio servers. Config file: ~/.cursor/mcp.json

⭐ Option A — HTTP (hosted, or your own container)

{
  "mcpServers": {
    "whoisfreaks": {
      "url": "https://mcp.whoisfreaks.com",
      "headers": { "Authorization": "Bearer your-api-key-here" }
    }
  }
}

For your own container use http://localhost:3100/mcp (start it with docker run -d -p 3100:3100 whoisfreaks/mcp-server:latest).


Option B — Docker via stdio (no port needed)

{
  "mcpServers": {
    "whoisfreaks": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "WHOISFREAKS_API_KEY=your-api-key-here",
        "--entrypoint", "java",
        "whoisfreaks/mcp-server:latest",
        "-jar", "app.jar"
      ]
    }
  }
}

Option C — JAR directly (requires Java 17)

{
  "mcpServers": {
    "whoisfreaks": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/whoisfreaks-mcp-server-2.1.0.jar"],
      "env": {
        "WHOISFREAKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Steps:

  1. Save ~/.cursor/mcp.json with your chosen option
  2. Restart Cursor
  3. Open the AI Panel (Cmd+L) → you should see a tools indicator showing WhoisFreaks tools
  4. Ask: Check the SSL certificate for github.com

3. Windsurf IDE

Windsurf (by Codeium) supports MCP via its Cascade AI sidebar.

Config file location:

OSPath
macOS~/.codeium/windsurf/mcp_config.json
Windows%USERPROFILE%\.codeium\windsurf\mcp_config.json
Linux~/.codeium/windsurf/mcp_config.json

⭐ Option A — Docker via stdio (recommended)

{
  "mcpServers": {
    "whoisfreaks": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "WHOISFREAKS_API_KEY=your-api-key-here",
        "--entrypoint", "java",
        "whoisfreaks/mcp-server:latest",
        "-jar", "app.jar"
      ]
    }
  }
}

Option B — JAR directly (requires Java 17)

{
  "mcpServers": {
    "whoisfreaks": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/whoisfreaks-mcp-server-2.1.0.jar"],
      "env": {
        "WHOISFREAKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Steps:

  1. Save the config with your chosen option
  2. Restart Windsurf
  3. Open Cascade sidebar → look for the MCP tools indicator (plug icon)
  4. Ask: Find all subdomains of tesla.com

Note: Windsurf requires Cascade to be in Write mode for tool use. Toggle it from the Cascade header if tools are not being called.


4. VS Code + GitHub Copilot

VS Code supports MCP tools through the GitHub Copilot extension (Chat Participants / Tools feature).

Config file (.vscode/mcp.json in your workspace, or ~/.vscode/mcp.json globally):

⭐ Option A — HTTP (hosted, or your own container)

{
  "servers": {
    "whoisfreaks": {
      "type": "http",
      "url": "https://mcp.whoisfreaks.com",
      "headers": { "Authorization": "Bearer your-api-key-here" }
    }
  }
}

For your own container use http://localhost:3100/mcp (start it with docker run -d -p 3100:3100 whoisfreaks/mcp-server:latest).

Option B — Docker via stdio

{
  "servers": {
    "whoisfreaks": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "WHOISFREAKS_API_KEY=your-api-key-here",
        "--entrypoint", "java",
        "whoisfreaks/mcp-server:latest",
        "-jar", "app.jar"
      ]
    }
  }
}

Option C — JAR directly (requires Java 17)

{
  "servers": {
    "whoisfreaks": {
      "type": "stdio",
      "command": "java",
      "args": ["-jar", "/absolute/path/to/whoisfreaks-mcp-server-2.1.0.jar"],
      "env": {
        "WHOISFREAKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Steps:

  1. Make sure you have the GitHub Copilot Chat extension installed (v1.99+)
  2. Save the config file above with your chosen option
  3. Open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I)
  4. Switch the model to Agent mode using the dropdown
  5. Click the Tools button — WhoisFreaks tools should appear in the list
  6. Ask: What are the MX records for github.com?

Requirement: VS Code 1.99+ and GitHub Copilot Chat extension are required for MCP tool support.


5. Continue.dev

Continue is an open-source AI coding assistant with MCP support for VS Code and JetBrains IDEs.

Config file (~/.continue/config.json):

⭐ Option A — HTTP (hosted, or your own container)

{
  "mcpServers": [
    {
      "name": "whoisfreaks",
      "url": "https://mcp.whoisfreaks.com/?apiKey=your-api-key-here",
      "transport": "streamable-http"
    }
  ]
}

For your own container use http://localhost:3100/mcp?apiKey=... (start it with docker run -d -p 3100:3100 whoisfreaks/mcp-server:latest).

Option B — Docker via stdio

{
  "mcpServers": [
    {
      "name": "whoisfreaks",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "WHOISFREAKS_API_KEY=your-api-key-here",
        "--entrypoint", "java",
        "whoisfreaks/mcp-server:latest",
        "-jar", "app.jar"
      ]
    }
  ]
}

Option C — JAR directly (requires Java 17)

{
  "mcpServers": [
    {
      "name": "whoisfreaks",
      "command": "java",
      "args": ["-jar", "/absolute/path/to/whoisfreaks-mcp-server-2.1.0.jar"],
      "env": {
        "WHOISFREAKS_API_KEY": "your-api-key-here"
      }
    }
  ]
}

Steps:

  1. Install the Continue extension from the VS Code Marketplace or JetBrains Plugin Marketplace
  2. Edit ~/.continue/config.json with your chosen option
  3. Reload the window (Cmd+Shift+P → Reload Window)
  4. Open Continue sidebar — tools from WhoisFreaks will be available in chat
  5. Ask: Look up IP geolocation for 1.1.1.1

6. Zed Editor

Zed has a built-in AI assistant with MCP support via its assistant configuration.

Config file (~/.config/zed/settings.json):

⭐ Option A — Docker via stdio (recommended)

{
  "assistant": {
    "mcp_servers": {
      "whoisfreaks": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "WHOISFREAKS_API_KEY=your-api-key-here",
          "--entrypoint", "java",
          "whoisfreaks/mcp-server:latest",
          "-jar", "app.jar"
        ]
      }
    }
  }
}

Option B — JAR directly (requires Java 17)

{
  "assistant": {
    "mcp_servers": {
      "whoisfreaks": {
        "command": "java",
        "args": ["-jar", "/absolute/path/to/whoisfreaks-mcp-server-2.1.0.jar"],
        "env": {
          "WHOISFREAKS_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

Steps:

  1. Open Zed → Zed menu → Settings (or Cmd+,)
  2. Add the mcp_servers block to your existing settings JSON using your chosen option
  3. Save and restart Zed
  4. Open the AI panel (Cmd+?) → tools will be listed under the tools indicator
  5. Ask: Is the domain myapp.io available?

Example Prompts

Once configured in any client above, try these prompts:

# WHOIS
Who owns the domain apple.com? Give me full WHOIS details.
Show me the complete ownership history for whoisfreaks.com.
Find all domains registered by admin@google.com.

# IP & ASN WHOIS
What organization owns the IP address 8.8.8.8?
Look up ASN information for AS15169.

# DNS
What are the MX and NS records for github.com?
Has facebook.com changed its IP addresses in the last 2 years? (DNS history)
Which domains are pointing to the IP 104.21.0.0? (reverse DNS)

# IP Intelligence
Where is 1.1.1.1 located? What ISP runs it?
Is 185.220.101.45 a Tor exit node or a VPN?

# Domain Tools
Is mycompany.io available to register? Suggest 5 alternatives.
Which of mycompany .com, .io, .ai and .dev are still available? (bulk availability)
List all known subdomains of tesla.com.
Find typosquats of 'paypal' registered recently. (domain typosquatting)
Are there phishing subdomains that imitate 'paypal' on other domains? (subdomain typosquatting)
Is suspicious-login-portal.com safe? Give me a verdict. (domain reputation)

# Bulk
Get the WHOIS records of these 20 domains and list their registrars and expiry dates.
Which of these IPs from my logs are VPNs, proxies or Tor exit nodes?

# Account
How many credits do I have left on my WhoisFreaks key?

# SSL
Check the SSL certificate for github.com — who issued it and when does it expire?

Environment Variables

VariableRequiredDescription
WHOISFREAKS_API_KEYstdio mode onlyYour API key from whoisfreaks.com/billing. Without it the server still starts and lists its tools, but every tool call returns a WHOISFREAKS_API_KEY is not set error. Not used in HTTP mode, where each request carries the caller's own key.
MCP_TRANSPORTNohttp to run the hosted HTTP server (same as the --http flag). The Docker image runs HTTP mode by default.
PORTNoHTTP port. Default: 3100.

Troubleshooting

API Errors

ProblemCauseFix
WHOISFREAKS_API_KEY is not set (stdio)Missing env varAdd -e WHOISFREAKS_API_KEY=your-key to the Docker command, or add it to the env block in your client config
No WhoisFreaks API key was sent (HTTP)Client sent no keyAdd Authorization: Bearer your-key, an X-API-Key header, or ?apiKey=your-key to the URL, then reconnect
Unauthorized (HTTP 401)Invalid or inactive API key, or the plan, credits or surcharge limit are used upThe message includes the API's own reason. Check the key and usage at whoisfreaks.com/billing, or ask the assistant to run apiKeyUsage
Not supported (HTTP 403)WhoisFreaks does not support the domain's extension (TLD), or it is inactiveTry another domain
No data found (HTTP 404)Domain/IP/ASN not in databaseDouble-check the input value is correct
Rate limit reached (HTTP 429)Too many requests per minuteWait for the number of seconds in the message, or upgrade your plan
Too large (HTTP 413)A bulk list has more than 100 itemsSplit the list; the bulk tools also refuse more than 100 items before calling the API
Timeout (HTTP 408)Upstream WHOIS server is slowRetry — some TLDs have slow WHOIS servers
did not answer within ... secondsThe API took too long (60 s for single lookups, 240 s for bulk lookups and typosquatting searches)Try again later

Docker Errors

ProblemCauseFix
Cannot connect to Docker daemonDocker Desktop not runningOpen Docker Desktop and wait for the engine to start
Container exits immediatelyPort in use or wrong entrypointCheck logs: docker logs whoisfreaks-mcp
port 3100 already in useAnother process on port 3100Stop it: docker rm -f whoisfreaks-mcp then retry
no such imageImage not pulled yetRun docker pull whoisfreaks/mcp-server:latest first
Claude Desktop: tools not appearing with Docker configDocker not in PATH seen by the appUse the full Docker path: /usr/local/bin/docker as the command
lstat deploy: no such file or directory (CI/CD)Relative path issue in GitHub ActionsUse ${{ github.workspace }}/deploy/Dockerfile for absolute paths
Gateway connection refused on port 3100Container not running or port not mappedRun docker ps — ensure -p 3100:3100 is in the run command
504 / timeouts behind NginxNginx proxy timeout shorter than a slow lookupAdd proxy_read_timeout 300s; and proxy_buffering off; to your Nginx location block

Client Errors

ProblemCauseFix
Tools not visible in clientConfig not saved or client not restartedSave config → fully quit and reopen the client
UnsupportedClassVersionError (JAR mode)Java version too oldUpgrade to Java 17+ (java -version to check)
Wrong JAR pathRelative path in configUse the full absolute path to the JAR
Cursor shows tools but doesn't call themAgent mode not enabledSwitch Cursor to Agent mode, not Chat mode
Claude Desktop skips whoisfreaks entryurl used in claude_desktop_config.jsonThat file needs command/args (stdio). For a URL, add a custom connector in Settings → Connectors instead
Client can't connect to /ssePre-2.0 SSE endpoint was removedUse the /mcp URL (Streamable HTTP)
Windsurf tools not calledWrong Cascade modeSwitch Cascade to Write mode from the Cascade header

Links

No installation packages available.

Remote