Installation Guide

Choose the installation method that best fits your environment and workflow. Each method has its own advantages and is designed for different use cases.

Prerequisites

Before installing, ensure you have:

  • WhoisXMLAPI Token - Get yours from whoisxmlapi.com
  • AI Client - Claude Desktop, Cursor, Claude Code, Gemini, or any MCP-compatible client

Additional requirements depend on your chosen installation method (detailed in each guide).

Installation Methods

☁️ Hosted Service (No Installation Required)

Easiest option - fully managed by WhoisXML API

No installation or setup required! Use our hosted MCP server directly.

Configuration Example:

{
  "mcpServers": {
    "whoisxmlapi": {
      "url": "https://mcp-hosted.whoisxmlapi.com/mcp",
      "headers": {
        "Authorization": "Bearer at_YOUR_API_KEY_HERE"
      }
    }
  }
}

Replace at_YOUR_API_KEY_HERE with your WhoisXML API key from whoisxmlapi.com.

Perfect for:

  • Getting started quickly without any installation
  • Users who want zero maintenance
  • Always staying up-to-date with the latest version
  • Production use without managing infrastructure

Advantages:

  • ✅ No installation or dependencies required
  • ✅ Always running the latest version
  • ✅ Managed by the WhoisXML API team
  • ✅ No maintenance or updates needed
  • ✅ Works with all MCP clients

Learn more about HTTP Server Mode →

Self-Hosted Options

If you prefer to host the server yourself, choose from these installation methods:

🐳 Docker Installation

Recommended for most users

Complete Docker Installation Guide →

docker pull whoisxmlapidotcom/mcp-whoisxmlapi:v1

Perfect for:

  • Desktop AI clients (Claude Desktop, Cursor)
  • Consistent environments across different machines
  • Users who want isolation and security
  • Production deployments

Advantages:

  • No local dependencies required
  • Automatic updates available
  • Security isolation
  • Works identically across all platforms
  • Easy cleanup and management

📦 npm Installation

Best for Node.js developers and CLI users

Complete npm Installation Guide →

npm install -g @whoisxmlapidotcom/mcp-whoisxmlapi

Perfect for:

  • CLI AI tools (Claude Code, Gemini CLI)
  • Node.js developers and workflows
  • Quick testing and development
  • CI/CD pipelines

Advantages:

  • Fastest setup for Node.js users
  • Automatic platform detection
  • Easy updates with npm
  • No Docker required
  • Integrates well with development workflows

💾 Binary Installation

For direct control and custom deployments

Complete Binary Installation Guide →

# Download and run directly
chmod +x mcp-whoisxmlapi
./mcp-whoisxmlapi --help

Perfect for:

  • Custom deployment scenarios
  • Resource-constrained environments
  • Users who prefer standalone executables
  • Specialized integration requirements

Advantages:

  • No external dependencies
  • Minimal resource footprint
  • Direct system integration
  • Maximum control over deployment

Quick Comparison

FeatureHosted ServiceDockernpmBinary
Setup SpeedInstant ⚡FastFastestMedium
InstallationNoneDocker onlyNode.js 22+ LTSNone
MaintenanceZeroUpdates needednpm updateManual download
Always Updated✅ AutomaticManualManualManual
Resource UsageZero (remote)MediumLowLowest
Uptime✅ ManagedSelf-managedSelf-managedSelf-managed

Choosing the Right Method

Choose Hosted Service if you:

  • Want to get started immediately with zero setup
  • Prefer zero maintenance and automatic updates
  • Don't want to manage server infrastructure
  • Want guaranteed uptime managed by the WhoisXML API team
  • Don't need to customize server configuration

Choose Docker if you:

  • Want the most reliable and consistent setup
  • Use desktop AI clients (Claude Desktop, Cursor)
  • Value security isolation
  • Want automatic dependency management
  • Plan to use in production

Choose npm if you:

  • Use CLI AI tools (Claude Code, Gemini CLI)
  • Are comfortable with Node.js
  • Want the fastest setup
  • Need frequent updates
  • Work in development environments

Choose Binary if you:

  • Need minimal resource usage
  • Want no external dependencies
  • Have custom deployment requirements
  • Need maximum control over the installation
  • Work in restricted environments

Installation Workflow

1. Choose Your Method

Click on one of the installation guides above based on your preferences and requirements.

2. Follow the Guide

Each installation guide provides:

  • Step-by-step instructions
  • Platform-specific details
  • Configuration examples
  • Troubleshooting tips

3. Configure Your AI Client

After installation, configure your AI client:

4. Verify Installation

Test your setup:

  • Ask your AI client to: "Look up WHOIS information for example.com"

Common Environment Variables

All installation methods use these environment variables:

  • WHOISXMLAPI_TOKEN ✅ Required

    • Description: Your API token
    • Example: "at-...abc123"

  • WHOISXMLAPI_HTTP_DEBUG (Optional)

    • Description: Debug log file path
    • Example: "/tmp/debug.log"

  • WHOISXMLAPI_DISABLED_TOOLS (Optional)

    • Description: Tools to disable
    • Example: "threat_intelligence"

Keep Your Token Secure

  • Never commit API tokens to version control
  • Use environment variables for token storage
  • Consider using different tokens for different environments
  • Rotate tokens regularly for enhanced security

Getting Help

Installation Issues

Each installation method has its own troubleshooting section:

General Support

Next Steps

After completing installation:

  1. Configure your AI client - Set up Claude Desktop, Cursor, etc.
  2. Server configuration - Advanced options and customization
  3. Explore tools - Learn about all available tools
  4. Set up debugging - Enable logging if needed

Quick Start Examples

Once installed, here are some quick configuration examples:

Hosted Service Configuration

{
  "mcpServers": {
    "whoisxmlapi": {
      "url": "https://mcp-hosted.whoisxmlapi.com/mcp",
      "headers": {
        "Authorization": "Bearer at_YOUR_API_KEY_HERE"
      }
    }
  }
}

Docker Configuration

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

npm Configuration

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": ["-y", "@whoisxmlapidotcom/mcp-whoisxmlapi"],
      "env": {"WHOISXMLAPI_TOKEN": "your-token-here"}
    }
  }
}

Binary Configuration

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "/usr/local/bin/mcp-whoisxmlapi",
      "env": {"WHOISXMLAPI_TOKEN": "your-token-here"}
    }
  }
}

Ready to get started? Choose your preferred installation method above! 🚀

Last Updated: