---
title: "MCP Server Integration | WhoisFreaks"
slug: "/integrations/third-party/mcp-server"
description: "Integrate WhoisFreaks MCP Server with third-party platforms and AI workflows to access domain, WHOIS, DNS, and IP intelligence data programmatically."
---

# MCP Server Integration

## 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.

## How to Install?

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

| Method | Requires | Best for |
| --- | --- | --- |
| Docker (pre-built image) | Docker only | Everyone — no Java or Maven neededRecommended |
| Build from source | Java 17 + Maven | Contributors / custom builds |

ⓘ Tip

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

## Tools Reference

The WHOIS Domain API delivers structured JSON or XML data with registry and registrar details when available. It organizes ownership information into separate objects like registrant, technical, billing, and administrative details alongside nameservers and key domain dates such as registration and expiry. The WHOIS Domain API’s structured format ensures seamless integration into your systems.

### WHOIS Tools

| Tool | Description |
| --- | --- |
| liveWhoisLookup | Real-time WHOIS data for any domain — registrar, registrant, dates, nameservers |
| whoisHistory | Complete ownership history timeline for a domain |
| reverseWhoisLookup | Find all domains registered by an email address, keyword, owner name, or company |

### IP & ASN WHOIS Tools

| Tool | Description |
| --- | --- |
| ipWhoisLookup | WHOIS registration data for any IPv4 or IPv6 address |
| asnWhoisLookup | WHOIS data for an Autonomous System Number (e.g. AS15169) |

### DNS Tools

| Tool | Description |
| --- | --- |
| dnsLookup | Live DNS records - A, AAAA, MX, NS, CNAME, SOA, TXT, SPF, or all |
| dnsHistory | Historical DNS records with full change timeline |
| reverseDnsLookup | Find all domains pointing to a given IP or nameserver |

### IP Intelligence Tools

| Tool | Description |
| --- | --- |
| ipGeolocation | Country, city, region, ISP, and coordinates for any IP address |
| ipSecurity | VPN, proxy, Tor exit node, bot, and threat intelligence for any IP |

### Domain Tools

| Tool | Description |
| --- | --- |
| domainAvailability | Check if a domain is available to register, with optional suggestions |
| subdomainLookup | Enumerate all known subdomains for a domain, with status and date filters |
| domainDiscovery | Find domains by keyword, including typosquatting and similar variants |

### SSL Tools

| Tool | Description |
| --- | --- |
| sslLookup | SSL/TLS certificate details - issuer, expiry, SANs, chain, and raw output |

## Quick Start

### Docker

Recommended

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](https://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"
      ]
    }
  }
}
```

## Build from Source

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

### Prerequisites:

| Requirement | Minimum Version | Notes |
| --- | --- | --- |
| Java (JDK) | 17  | Check with`java -version` |
| Maven | 3.8 | Check with`mvn -version` |
| WhoisFreaks API Key | —   | Get yours at [whoisfreaks.com/signup](https://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-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`

## 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:**

| OS  | Path |
| --- | --- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%Claudeclaude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

#### Option A — 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`.

## 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

| Variable | Required | Description |
| --- | --- | --- |
| `WHOISFREAKS_API_KEY` | Yes | Your API key from [whoisfreaks.com/billing](https://billing.whoisfreaks.com/). All 14 tools call`api.whoisfreaks.com`directly using this key — no other variables are needed. |

## Troubleshooting

### API Errors

| Problem | Cause | Fix |
| --- | --- | --- |
| `WHOISFREAKS_API_KEY is not set` | Missing env var | Add`-e WHOISFREAKS_API_KEY=your-key`to the Docker command, or add it to the`env`block in your client config |
| `Unauthorized (HTTP 401/403)` | Invalid or inactive API key | Verify the key at billing.whoisfreaks.com |
| `No data found (HTTP 404)` | Domain/IP/ASN not in database | Double-check the input value is correct |
| `Rate limit reached (HTTP 429)` | Too many requests | Slow down or upgrade your plan |
| `Credit limit exceeded (HTTP 413)` | Credits exhausted | Add credits at billing.whoisfreaks.com |
| `Timeout (HTTP 408)` | Upstream WHOIS server is slow | Retry - some TLDs have slow WHOIS servers |

### Docker Errors

| Problem | Cause | Fix |
| --- | --- | --- |
| `Cannot connect to Docker daemon` | Docker Desktop not running | Open Docker Desktop and wait for the engine to start |
| Container exits immediately | Missing API key or wrong entrypoint | Check logs:`docker logs whoisfreaks-mcp` |
| `port 3100 already in use` | Another process on port 3100 | Stop it:`docker rm -f whoisfreaks-mcp`then retry |
| `no such image` | Image not pulled yet | Run`docker pull whoisfreaks/mcp-server:latest`first |
| Claude Desktop: tools not appearing with Docker config | Docker not in PATH seen by the app | Use 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 Actions | Use`${{ github.workspace }}/deploy/Dockerfile`for absolute paths |
| `Gateway connection refused on port 3100` | Container not running or port not mapped | Run `docker ps`- ensure`-p 3100:3100`is in the run command |
| SSE connection drops after a few seconds | Nginx proxy timeout | Add`proxy_read_timeout 3600s;`to your Nginx location block |

### Client Errors

| Problem | Cause | Fix |
| --- | --- | --- |
| Tools not visible in client | Config not saved or client not restarted | Save config → fully quit and reopen the client |
| `UnsupportedClassVersionError`(JAR mode) | Java version too old | Upgrade to Java 17+ (java -version to check) |
| Wrong JAR path | Relative path in config | Use the full absolute path to the JAR |
| Cursor shows tools but doesn't call them | Agent mode not enabled | Switch Cursor to Agent mode, not Chat mode |
| Claude Desktop skips whoisfreaks entry | SSE URL used instead of stdio | Claude Desktop requires`command/args`- not url. Use the Docker stdio config shown above |
| Windsurf tools not called | Wrong Cascade mode | Switch Cascade to Write mode from the Cascade header |