Docker Installation

Docker provides the most reliable and consistent way to run the WhoisXML API MCP Server. With Docker, you get automatic dependency management, security isolation, and guaranteed compatibility across all platforms.

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

Prerequisites

Docker installed - See our Docker Installation & Usage Guide if you need to install Docker
WhoisXMLAPI token - Get yours from whoisxmlapi.com
AI client - Any MCP-compatible client

Quick Start

Step 1: Pull the Docker Image

Pull the latest version of the WhoisXML API MCP Server:

docker pull whoisxmlapidotcom/mcp-whoisxmlapi:v1

Step 2: Test the Installation

Verify the image works correctly:

# Test with help command
docker run --rm whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

# Test with your API token
docker run --rm -e WHOISXMLAPI_TOKEN=your-token-here \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

Step 3: Configure Your AI Client

Add the Docker configuration to your AI client's 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"
      }
    }
  }
}

Client-Specific Setup

Different AI clients have different ways to configure MCP servers. For detailed setup instructions for your specific client, see our AI Client Configuration Guide.

Configuration Options

Basic Configuration

Now that you have configured your AI client, you can add the Docker configuration 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"
      }
    }
  }
}

Advanced Configuration

For production or advanced use cases:

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

Advanced options explained:

--memory=512m - Limit container memory usage
--cpus=1.0 - Limit CPU usage
-v /tmp:/tmp - Mount volume for log files
--timeout 30s - Custom API timeout
env - Environment variables for debugging and tool management

HTTP Server Mode

For web applications or multiple client access:

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

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

Environment Variables

All environment variables are passed to the container using the --env flag and configured in the env section:

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

Always use the pattern:

Add --env VARIABLE_NAME to the args array
Set the actual value in the env object

{
  "args": [
    "run", "--rm", "-i",
    "--env", "WHOISXMLAPI_TOKEN",
    "--env", "WHOISXMLAPI_HTTP_DEBUG",
    "whoisxmlapidotcom/mcp-whoisxmlapi:v1"
  ],
  "env": {
    "WHOISXMLAPI_TOKEN": "your-token-here",
    "WHOISXMLAPI_HTTP_DEBUG": "/tmp/debug.log"
  }
}

Debugging and Logging

Enable HTTP Debugging

To debug API calls, enable HTTP logging:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env", "WHOISXMLAPI_TOKEN",
        "--env", "WHOISXMLAPI_HTTP_DEBUG",
        "-v", "/tmp:/tmp",
        "whoisxmlapidotcom/mcp-whoisxmlapi:v1"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token-here",
        "WHOISXMLAPI_HTTP_DEBUG": "/tmp/whoisxmlapi-debug.log"
      }
    }
  }
}

To view the logs, you must ask a question to your AI client that will trigger the HTTP debugging first:

# Monitor logs in real-time
tail -f /tmp/whoisxmlapi-debug.log

# View recent logs
cat /tmp/whoisxmlapi-debug.log

Container Debugging

Debug container issues:

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

# Test container startup
docker run --rm -e WHOISXMLAPI_TOKEN=test-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

# Check container logs (if running in background)
docker logs <container-id>

# Inspect container configuration
docker inspect <container-id>

Updates and Maintenance

Updating the Server

To update to the latest version:

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

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

The next time your AI client starts, it will use the updated image automatically.

Cleanup

Remove unused Docker resources:

# Remove stopped containers
docker container prune

# Remove unused images
docker image prune

# Remove all unused resources
docker system prune

Security Considerations

Container Security

Docker provides several security benefits:

Process isolation - Server runs in an isolated environment
Network isolation - Limited network access
Filesystem isolation - No access to host filesystem unless explicitly mounted
Resource limits - Memory and CPU usage can be controlled

Best Practices

Never commit tokens - Always use environment variables
Limit resources - Use --memory and --cpus flags for production
Regular updates - Pull latest images regularly
Monitor logs - Enable debugging only when needed
Secure volumes - Only mount necessary directories

Token Security

{
  "env": {
    "WHOISXMLAPI_TOKEN": "your-actual-token-here"
  }
}

✅ Good practices:

Store tokens in secure configuration files
Use different tokens for different environments
Rotate tokens regularly
Never log or display tokens

❌ Avoid:

Hardcoding tokens in documentation
Committing tokens to version control
Sharing tokens in screenshots or logs

Troubleshooting

Common Issues

"Container exits immediately"

# Check if token is set correctly
docker run --rm -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

"Bind for 0.0.0.0:3000 failed: port is already allocated"

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

You can also use a different port:

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

"Permission denied"

# Try with sudo (Linux)
sudo docker run --rm -e WHOISXMLAPI_TOKEN=your-token \
  whoisxmlapidotcom/mcp-whoisxmlapi:v1 --help

# Check Docker daemon status
docker info

"Port already in use" (HTTP mode)

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

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

Getting Help

For more troubleshooting assistance:

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

Next Steps

Now that you have Docker installed and configured:

Configure your AI client - See AI Client Configuration for detailed setup instructions
Explore available tools - Check the Tools Reference
Learn about advanced features - Review Server Configuration
Set up monitoring - Enable HTTP Debugging if needed

AI Client Configuration - Configure any MCP-compatible client
Server Configuration - Advanced server options
Tools Reference - All available WhoisXMLAPI tools
Docker Installation & Usage - Install Docker itself and learn container usage