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.

Two ways to run it — pick what fits your setup:

Once running, connect it to any MCP client via stdio (local) or HTTP/SSE on port 3100 (remote VM).

Table of Contents

1. Tools Reference (14 tools)

2. Quick Start

3. Prerequisites

4. Platform Integration

5. Example Prompts

6. Troubleshooting

Tools Reference

WHOIS Tools

IP & ASN WHOIS Tools

DNS Tools

IP Intelligence Tools

Domain Tools

SSL Tools

Quick Start

⭐ Recommended — Docker

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

Get your free API key first: whoisfreaks.com/signup

Option 1 — Direct `docker run` (simplest)

docker run -d \
  --name whoisfreaks-mcp \
  --restart unless-stopped \
  -p 3100:3100 \
  -e WHOISFREAKS_API_KEY=your-api-key-here \
  whoisfreaks/mcp-server:latest

The MCP gateway is now live at `http://localhost:3100/sse`.

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"
    environment:
      WHOISFREAKS_API_KEY: your-api-key-here

Start it:

docker compose up -d

Or use a `.env` file instead of hardcoding the key (recommended):

# Create .env file (never commit this to git)
echo "WHOISFREAKS_API_KEY=your-api-key-here" > .env
docker compose up -d

Verify Docker is working

# Container should show as "Up"
docker ps

# SSE endpoint should respond
curl http://localhost:3100/health
# → {"status":"ok"}

# List all 14 registered tools
curl http://localhost:3100/tools/list

Use with Claude Desktop (Docker stdio mode)

Claude Desktop requires stdio transport. Override the Docker entrypoint to bypass `mcp-proxy` and run the JAR directly:

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

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-1.0.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-1.0.0.jar`

Prerequisites

Platform Integration

1. Claude Desktop

The most popular MCP client. Claude Desktop launches the MCP server as a subprocess on startup and communicates via stdio — it does not support SSE/HTTP URLs.

Config file location:

⭐ 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-1.0.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 14 WhoisFreaks tools listed

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

2. Cursor IDE

Cursor supports both stdio and SSE transports. Config file: `~/.cursor/mcp.json`

⭐ Option A — Docker via SSE (recommended)

{
  "mcpServers": {
    "whoisfreaks": {
      "url": "http://localhost:3100/sse",
      "transport": "sse"
    }
  }
}

> Start the Docker container first: `docker run -d -p 3100:3100 -e WHOISFREAKS_API_KEY=your-key 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-1.0.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:

⭐ 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-1.0.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 — Docker via SSE (recommended, container must be running)

{
  "servers": {
    "whoisfreaks": {
      "type": "sse",
      "url": "http://localhost:3100/sse"
    }
  }
}

> Start the container first: `docker run -d -p 3100:3100 -e WHOISFREAKS_API_KEY=your-key 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-1.0.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 — Docker via SSE (recommended, container must be running)

{
  "mcpServers": [
    {
      "name": "whoisfreaks",
      "url": "http://localhost:3100/sse",
      "transport": "sse"
    }
  ]
}

> Start the container first: `docker run -d -p 3100:3100 -e WHOISFREAKS_API_KEY=your-key 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-1.0.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-1.0.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.
List all known subdomains of tesla.com.
Find domains similar to 'google' — possible typosquatting targets.

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

Environment Variables

Troubleshooting

API Errors

Docker Errors

Client Errors

Links

• WhoisFreaks API Documentation: https://whoisfreaks.com/documentation
• API Key & Billing: https://whoisfreaks.com/billing
• MCP Protocol Specification: https://modelcontextprotocol.io
• MCP Inspector (test tool): `npx @modelcontextprotocol/inspector`
• Issues & Support: Open an issue on GitHub