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

   • ⭐ Recommended — Docker

   • Build from Source

3. Prerequisites

4. Platform Integration

   • 1. Claude Desktop

   • 2. Cursor IDE

   • 3. Windsurf IDE

   • 4. VS Code + GitHub Copilot

   • 5. Continue.dev

   • 6. Zed Editor

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