Docker Installation & Usage

Docker is a containerization platform that provides the most reliable and consistent way to run the WhoisXML API MCP Server. This comprehensive guide covers both Docker Desktop installation and MCP server usage.

Why Choose Docker?

No local dependencies - everything runs in an isolated container
Automatic updates - pull the latest version anytime
Security isolation - server runs in a sandboxed environment
Cross-platform consistency - works identically on all operating systems
Easy cleanup - remove containers without leaving traces

Part 1: Docker Installation

System Requirements

Before installing Docker Desktop, ensure your system meets these requirements:

Windows Requirements

Windows 10/11: 64-bit Pro, Enterprise, or Education (Build 19041 and higher)
Windows 10/11 Home: 64-bit (Build 19041 and higher) with WSL 2
Hardware: Virtualization support enabled in BIOS
Memory: Minimum 4GB RAM (8GB recommended)
Storage: At least 4GB available disk space

macOS Requirements

macOS: 10.15 (Catalina) or higher
Hardware:
- Intel: 2010 MacBook Pro or newer
- Apple Silicon: M1/M2/M3 Macs fully supported
Memory: Minimum 4GB RAM (8GB recommended)
Storage: At least 4GB available disk space

Linux Requirements

Distributions: Ubuntu 20.04+, Debian 10+, CentOS 8+, Fedora 35+
Architecture: x86_64/amd64, ARM64
Kernel: Version 3.10 or higher
Memory: Minimum 4GB RAM (8GB recommended)
Storage: At least 4GB available disk space

Installing Docker Desktop

Windows Installation

Step 1: Enable Required Features

For Windows 10/11 Pro, Enterprise, or Education:

Enable Hyper-V:
- Open "Turn Windows features on or off"
- Check "Hyper-V" and click OK
- Restart when prompted

For Windows 10/11 Home:

Ensure you have WSL 2 installed: WSL 2 is required for Docker Desktop.
Restart your computer when prompted

Step 2: Download and Install Docker Desktop

Download Docker Desktop:
- Visit docker.com/products/docker-desktop
- Click "Download for Windows"
Install Docker Desktop:
- Run the downloaded installer
- Follow the installation wizard
- Choose appropriate configuration options:
  - Use WSL 2 (recommended for Windows Home)
  - Add to PATH (recommended)
Start Docker Desktop:
- Launch Docker Desktop from Start Menu
- Complete the initial setup wizard
- Sign in to Docker Hub (optional but recommended)

macOS Installation

Step 1: Download Docker Desktop

Download the appropriate version:
- Intel Macs: Download "Mac with Intel chip"
- Apple Silicon Macs: Download "Mac with Apple chip"
Install Docker Desktop:
- Open the downloaded .dmg file
- Drag Docker to Applications folder
- Launch Docker from Applications

Step 2: Complete Setup

Grant permissions:
- Allow Docker to use privileged access
- Enter your password when prompted
Start Docker Desktop:
- Docker Desktop will appear in the menu bar
- Wait for Docker to start (whale icon should be steady)

Linux Installation

Ubuntu/Debian:

# Update package index
sudo apt-get update

# Install packages to allow apt to use a repository over HTTPS
sudo apt-get install ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Set up the repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group (optional, to avoid using sudo)
sudo usermod -aG docker $USER
newgrp docker

CentOS/RHEL/Fedora:

# Install Docker using the official script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group (optional)
sudo usermod -aG docker $USER
newgrp docker

Verify Installation

Test that Docker is working correctly:

# Check Docker version
docker --version

# Test Docker installation
docker run hello-world

# Check Docker status
docker info

Alternative Container Solutions

While this guide focuses on Docker Desktop, other container solutions are available:

Rancher Desktop - Open-source Docker Desktop alternative
Podman Desktop - Red Hat's container solution
Lima - Lightweight VM manager for macOS
Colima - Container runtime for macOS with minimal setup

Compatibility Note

Daemonless environments such as podman might not be able to run the Docker image exactly as documented. Most examples in this guide assume Docker Desktop or Docker Engine.

Part 2: WhoisXML API MCP Server Usage

Docker Hub Repository

The official WhoisXML API MCP Server image is available at:

whoisxmlapidotcom/mcp-whoisxmlapi:v1

We provide container images for:

Linux x86_64 (Intel/AMD processors)
Linux ARM64 (to be executed on Apple Silicon and ARM-based processors)
Windows containers are not provided

ARM64 Note

Since containers aren't natively supported on macOS, the macOS Docker Desktop will default to using Linux ARM64 images (for Apple Silicon and ARM-based processors) or Linux x86_64 images (for Intel/AMD processors).

Image Versioning

The Docker image uses semantic versioning:

# Pinned to the latest v1 version (recommended)
whoisxmlapidotcom/mcp-whoisxmlapi:v1

# Pinned to a specific version
whoisxmlapidotcom/mcp-whoisxmlapi:v1.0.0

# Latest tag (not recommended for production)
whoisxmlapidotcom/mcp-whoisxmlapi:latest

Version Recommendation

Always use a specific version tag (like v1) rather than latest to ensure stability and avoid breaking changes.

Quick Start

Pull the Image

Most AI clients automatically pull the image, but you can pull it manually:

docker pull whoisxmlapidotcom/mcp-whoisxmlapi:v1

Basic Usage (stdio mode)

For direct testing (most AI clients handle this automatically):

docker run --rm -i -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1

Note for AI Clients

Running the image directly in stdio mode is primarily for testing. AI clients typically manage their own container instances and ignore manual executions.

HTTP Server Mode (Streamable HTTP)

This mode uses streamable HTTP transport, which automatically provides both direct HTTP responses and Server-Sent Events (SSE) streaming capabilities based on the request type and client needs. The server intelligently negotiates the best transport method for each request.

For web applications or multiple client access:

docker run --rm \
  -p 3000:3000 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 \
  --http --http-port 3000

AI Client Configuration

Claude Desktop / Cursor

Add this to your MCP configuration file:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env", "WHOISXMLAPI_TOKEN",
        "whoisxmlapidotcom/mcp-whoisxmlapi:v1"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here"
      }
    }
  }
}

Claude Code

Use the Docker option when adding the MCP server:

claude mcp add whoisxmlapi \
  --env WHOISXMLAPI_TOKEN=your-token-here \
  -- docker run --rm -i --env WHOISXMLAPI_TOKEN \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1

Advanced Configuration

With debugging, resource limits, and custom options:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--memory=512m",
        "--cpus=1.0",
        "--env", "WHOISXMLAPI_TOKEN",
        "--env", "WHOISXMLAPI_HTTP_DEBUG",
        "--env", "WHOISXMLAPI_DISABLED_TOOLS",
        "-v", "/tmp:/tmp",
        "whoisxmlapidotcom/mcp-whoisxmlapi:v1",
        "--timeout", "30s"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here",
        "WHOISXMLAPI_HTTP_DEBUG": "/tmp/whoisxmlapi-debug.log",
        "WHOISXMLAPI_DISABLED_TOOLS": "threat_intelligence"
      }
    }
  }
}

Environment Variables

All environment variables are passed using the --env flag:

WHOISXMLAPI_TOKEN ✅ Required
- Description: Your API token
- Example: "wxt-...abc123"
WHOISXMLAPI_HTTP_DEBUG (Optional)
- Description: Debug log file path
- Example: "/tmp/debug.log"
WHOISXMLAPI_DISABLED_TOOLS (Optional)
- Description: Comma-separated list of tools to disable
- Example: "threat_intelligence,reverse_whois"

Setting Environment Variables

Method 1: Direct specification

docker run --rm \
  -e WHOISXMLAPI_TOKEN="your-token" \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1

Method 2: From host environment

# Set environment variable first
export WHOISXMLAPI_TOKEN="your-token"

# Pass to container
docker run --rm \
  -e WHOISXMLAPI_TOKEN \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1

Debugging and Monitoring

Finding Running Containers

# List all running containers
docker ps

# Filter for MCP containers
docker ps --filter "ancestor=whoisxmlapidotcom/mcp-whoisxmlapi"

# Show detailed format
docker ps --format "table {{.Names}}\t{{.ID}}\t{{.Status}}\t{{.Ports}}"

Container Logs

# View recent logs
docker logs <container-id-or-name>

# Follow logs in real-time
docker logs -f <container-id-or-name>

# Show last 50 lines with timestamps
docker logs -t --tail 50 <container-id-or-name>

# Show logs since specific time
docker logs --since="2024-01-15T10:00:00" <container-id-or-name>

Container Inspection

# Inspect container configuration
docker inspect <container-id-or-name>

# Check environment variables
docker inspect <container-id-or-name> | grep -A 10 "Env"

Enable HTTP Debugging

For detailed API debugging:

# Mount volume for log file access
docker run --rm -i \
  -v /tmp:/tmp \
  -e WHOISXMLAPI_TOKEN=your-token \
  -e WHOISXMLAPI_HTTP_DEBUG=/tmp/whoisxmlapi-debug.log \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1

Then monitor the logs:

tail -f /tmp/whoisxmlapi-debug.log

Performance and Security

Resource Management

# Set memory and CPU limits
docker run --rm \
  --memory=512m \
  --cpus=1.0 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1

Security Considerations

Container isolation: Server runs in isolated environment with limited access
No filesystem access by default unless explicitly mounted
Environment variables only passed if explicitly specified
Network access limited to outbound API calls

Volume Mounts

Only mount necessary directories:

# Mount specific directory for logs
docker run --rm -i \
  -v /tmp:/tmp \
  -e WHOISXMLAPI_HTTP_DEBUG=/tmp/debug.log \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1

Updates and Maintenance

Updating the Server

# Pull latest version
docker pull whoisxmlapidotcom/mcp-whoisxmlapi:v1

# Remove old images (optional)
docker images | grep mcp-whoisxmlapi
docker rmi <old-image-id>

Cleanup

# Remove stopped containers
docker container prune

# Remove unused images
docker image prune

# Remove all unused resources
docker system prune

Docker Container Architecture

Container Details

Base: Distroless image (no shell, minimal attack surface)
Entrypoint: MCP server binary runs directly
Communication: stdio mode uses -i flag for standard input
Logging: All output goes to stdout/stderr (visible in docker logs)
Size: Optimized for minimal footprint

Troubleshooting

Common Docker Issues

Container won't start:

# Check if image exists
docker images | grep mcp-whoisxmlapi

# Test with minimal config
docker run --rm -e WHOISXMLAPI_TOKEN=test \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

Permission issues:

# Check Docker daemon status
docker info

# Verify user permissions (Linux)
groups | grep docker

Port conflicts (HTTP server mode):

# Check what's using the port
lsof -i :3000

# Use different port
docker run --rm -p 8080:8080 \
  -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 \
  --http --http-port 8080

Getting Help

For comprehensive Docker troubleshooting:

Docker Troubleshooting - Docker-specific issues and solutions
General Troubleshooting - General MCP server issues
HTTP Debugging - API and networking issues

AI Client Configuration - Configure Claude Desktop, Cursor, etc.
Server Configuration - Advanced server options
Tools Reference - All available WhoisXMLAPI tools