Binary Installation

The binary installation provides a standalone executable with no external dependencies. This is perfect for environments where you want direct control over the deployment, don't want to use Docker, or need to integrate with custom systems.

Why Choose Binary Installation?

  • No dependencies - Single executable file, no Docker or Node.js required
  • Direct control - Full control over installation location and permissions
  • Custom deployment - Perfect for CI/CD, automation, and custom integration
  • Minimal footprint - Smallest possible resource usage

Prerequisites

  • WhoisXMLAPI token - Get yours from whoisxmlapi.com
  • AI client - Any MCP-compatible client
  • Terminal access - For installation and configuration

Supported Platforms

The WhoisXML API MCP Server binary is available for:

  • Linux (x86_64, ARM64)
  • macOS (Intel x86_64, Apple Silicon ARM64)
  • Windows (x86_64, ARM64)

Download and Installation

Step 1: Download the Binary

Visit the Downloads page to get the appropriate binary for your platform:

Quick platform detection:

# Check your platform
uname -m  # Shows architecture (x86_64, arm64, etc.)
uname -s  # Shows OS (Linux, Darwin for macOS)

Step 2: Install the Binary

macOS and Linux

# Configure the version and architecture
VERSION="v1.0.0"  # Replace with the latest version
OS=linux
ARCH=amd64

# Create the filename
FILENAME="mcp-whoisxmlapi_${OS}_${ARCH}.tar.gz"

# Download
curl -L -o "${FILENAME}" "https://mcp.whoisxmlapi.com/binaries/${VERSION}/${FILENAME}"

# Extract the binary
tar -xzf "${FILENAME}"

# Make executable
chmod +x mcp-whoisxmlapi

# Test the binary
./mcp-whoisxmlapi --version
./mcp-whoisxmlapi --help

Install to system PATH (optional):

# Move to system bin directory
sudo mv mcp-whoisxmlapi /usr/local/bin/

# Or create symlink
sudo ln -s $(pwd)/mcp-whoisxmlapi /usr/local/bin/mcp-whoisxmlapi

# Test system-wide access
mcp-whoisxmlapi --help

Windows

# Configure the version and architecture
$VERSION = "v1.0.0"  # Replace with the latest version
$OS = "windows"
$ARCH = "amd64"

# Create the filename
$FILENAME = "mcp-whoisxmlapi_${OS}_${ARCH}.tar.gz"

# Download
Invoke-WebRequest -Uri "https://mcp.whoisxmlapi.com/binaries/$VERSION/$FILENAME" -OutFile $FILENAME

# Extract the binary
tar -xzf $FILENAME

# Test the binary (Windows binary should be .exe)
.\mcp-whoisxmlapi.exe --version
.\mcp-whoisxmlapi.exe --help

Add to PATH (optional):

# Move to a directory in PATH
Move-Item .\mcp-whoisxmlapi.exe C:\Windows\System32\

# Or add current directory to PATH
$env:PATH += ";$(Get-Location)"

# Test system-wide access
mcp-whoisxmlapi --version

Step 3: Handle Security (macOS)

macOS may quarantine downloaded binaries. Remove quarantine attributes:

# Remove quarantine attribute
xattr -dr com.apple.quarantine ./mcp-whoisxmlapi

# Alternative: Allow in System Preferences
# 1. Try to run the binary - you'll get a security warning
# 2. Go to System Preferences → Security & Privacy → General
# 3. Click "Allow Anyway" next to the blocked binary
# 4. Try running again and click "Open"

Quick Start

Step 1: Test Installation

Verify the binary works correctly:

# Test help output
./mcp-whoisxmlapi --help

# Check version
./mcp-whoisxmlapi --version

Step 2: Configure Your AI Client

Add the binary configuration to your AI client's MCP configuration file:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "/full/path/to/mcp-whoisxmlapi",
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here"
      }
    }
  }
}

Use Absolute Paths

Always use the full path to the binary in MCP configurations. Relative paths may not work correctly in all clients.

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

Minimal setup for any MCP client:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "/path/to/binary/mcp-whoisxmlapi",
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here"
      }
    }
  }
}

Advanced Configuration

With custom options and debugging:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "/usr/local/bin/mcp-whoisxmlapi",
      "args": [
        "--timeout", "30s",
        "--disabled-tools", "threat_intelligence,reverse_whois"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here",
        "WHOISXMLAPI_HTTP_DEBUG": "/tmp/whoisxmlapi-debug.log"
      }
    }
  }
}

HTTP Server Mode

For web applications:

# Basic HTTP mode
./mcp-whoisxmlapi --http --http-port 3000

# With environment variable
WHOISXMLAPI_TOKEN=your-token ./mcp-whoisxmlapi --http

# Custom port
./mcp-whoisxmlapi --http --http-port 8080

Command Line Options

The binary supports these command-line flags:

  • --api-base-url

    • Description: Custom API base URL
    • Default: https://www.whoisxmlapi.com
    • Example: --api-base-url https://api.custom.com

  • --timeout

    • Description: API request timeout
    • Default: 10s
    • Example: --timeout 30s

  • --disabled-tools

    • Description: Comma-separated list of tools to disable
    • Default: (none)
    • Example: --disabled-tools threat_intelligence,reverse_whois

  • --http

    • Description: Enable HTTP server mode
    • Default: false
    • Example: --http

  • --http-port

    • Description: HTTP server port
    • Default: 3000
    • Example: --http-port 8080

  • --help

    • Description: Show help message
    • Example: --help

  • --version

    • Description: Show version information
    • Example: --version

Usage Examples

# Basic usage with token
WHOISXMLAPI_TOKEN=your-token ./mcp-whoisxmlapi

# Custom timeout
./mcp-whoisxmlapi --timeout 30s

# Disable specific tools
./mcp-whoisxmlapi --disabled-tools threat_intelligence,reverse_whois

# HTTP mode with custom port
./mcp-whoisxmlapi --http --http-port 8080

# Combine multiple options
WHOISXMLAPI_TOKEN=your-token ./mcp-whoisxmlapi \
  --timeout 30s \
  --disabled-tools threat_intelligence \
  --http --http-port 3000

Environment Variables

Configure the server using environment variables:

  • 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"

  • WHOISXMLAPI_TIMEOUT (Optional)

    • Description: API request timeout
    • Example: "30s"

Setting Environment Variables

Temporary (current session):

# Linux/macOS
export WHOISXMLAPI_TOKEN="your-token-here"
export WHOISXMLAPI_HTTP_DEBUG="/tmp/debug.log"
./mcp-whoisxmlapi --help

# Windows PowerShell
$env:WHOISXMLAPI_TOKEN="your-token-here"
$env:WHOISXMLAPI_HTTP_DEBUG="C:\temp\debug.log"
.\mcp-whoisxmlapi.exe --help

# Windows Command Prompt
set WHOISXMLAPI_TOKEN=your-token-here
set WHOISXMLAPI_HTTP_DEBUG=C:\temp\debug.log
mcp-whoisxmlapi.exe --help

Permanent (shell profile):

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
echo 'export WHOISXMLAPI_TOKEN="your-token-here"' >> ~/.bashrc
echo 'export WHOISXMLAPI_HTTP_DEBUG="/tmp/whoisxmlapi-debug.log"' >> ~/.bashrc
source ~/.bashrc

Installation Locations

System-wide installation:

  • Linux: /usr/local/bin/mcp-whoisxmlapi
  • macOS: /usr/local/bin/mcp-whoisxmlapi
  • Windows: C:\Program Files\mcp-whoisxmlapi\mcp-whoisxmlapi.exe

User-specific installation:

  • Linux/macOS: ~/bin/mcp-whoisxmlapi (add ~/bin to PATH)
  • Windows: %USERPROFILE%\bin\mcp-whoisxmlapi.exe

Project-specific installation:

  • Keep binary in project directory: ./bin/mcp-whoisxmlapi
  • Use absolute paths in configuration files

PATH Configuration

Linux/macOS:

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export PATH="$HOME/bin:$PATH"

# Or add system-wide
echo 'export PATH="/usr/local/bin:$PATH"' >> /etc/profile

Windows:

# Add to user PATH
$oldPath = [Environment]::GetEnvironmentVariable("PATH", "User")
[Environment]::SetEnvironmentVariable("PATH", "$oldPath;C:\your\binary\path", "User")

# Add to system PATH (requires admin)
$oldPath = [Environment]::GetEnvironmentVariable("PATH", "Machine")
[Environment]::SetEnvironmentVariable("PATH", "$oldPath;C:\your\binary\path", "Machine")

Updates and Maintenance

Updating the Binary

# Check current version
./mcp-whoisxmlapi --version

# Download new version (same process as initial installation)
VERSION="v1.0.0"  # Set to the new version you want
OS=linux          # Set your OS
ARCH=amd64        # Set your architecture
FILENAME="mcp-whoisxmlapi_${OS}_${ARCH}.tar.gz"

curl -L -o "${FILENAME}" "https://mcp.whoisxmlapi.com/binaries/${VERSION}/${FILENAME}"

# Extract the binary
tar -xzf "${FILENAME}"

# Make executable
chmod +x mcp-whoisxmlapi

# Replace old binary (backup first if desired)
cp mcp-whoisxmlapi mcp-whoisxmlapi.backup
# The new binary is already extracted as mcp-whoisxmlapi

# Verify update
./mcp-whoisxmlapi --version

Backup and Restore

# Backup current binary
cp mcp-whoisxmlapi mcp-whoisxmlapi.backup

# Restore from backup if needed
cp mcp-whoisxmlapi.backup mcp-whoisxmlapi

Cleanup

# Remove binary
rm /usr/local/bin/mcp-whoisxmlapi

# Remove from PATH (edit shell profile)
# Remove any export PATH lines that include the binary directory

Debugging and Logging

Enable HTTP Debugging

# Set debug log file
export WHOISXMLAPI_HTTP_DEBUG="/tmp/whoisxmlapi-debug.log"
./mcp-whoisxmlapi --help

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

Binary Debugging

# Check binary details
file ./mcp-whoisxmlapi
ldd ./mcp-whoisxmlapi  # Linux: check shared libraries
otool -L ./mcp-whoisxmlapi  # macOS: check shared libraries

# Check permissions
ls -la ./mcp-whoisxmlapi

# Test execution
./mcp-whoisxmlapi --help 2>&1

Troubleshooting

Common Issues

"Permission denied"

# Fix permissions
chmod +x ./mcp-whoisxmlapi

# Check if executable
ls -la ./mcp-whoisxmlapi

"No such file or directory" (Linux)

# Check if 32-bit binary on 64-bit system
file ./mcp-whoisxmlapi

# Install required libraries (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install libc6

# Check architecture compatibility
uname -m

"Command not found"

# Use absolute path
/full/path/to/mcp-whoisxmlapi --help

# Check PATH
echo $PATH
which mcp-whoisxmlapi

# Verify binary location
ls -la ./mcp-whoisxmlapi

macOS Security Issues

# Remove quarantine
xattr -dr com.apple.quarantine ./mcp-whoisxmlapi

# Check quarantine status
xattr -l ./mcp-whoisxmlapi

# Alternative: System Preferences method described above

Windows Security Issues

# Check file properties and unblock if needed
Get-Item .\mcp-whoisxmlapi.exe | Unblock-File

# Run as administrator if needed
Start-Process .\mcp-whoisxmlapi.exe -Verb RunAs -ArgumentList "--help"

Architecture Mismatch

Wrong architecture downloaded:

# Check your system
uname -m                    # x86_64, arm64, etc.
getconf LONG_BIT           # 32 or 64 bit

# Re-download correct binary for your platform

Getting Help

For more troubleshooting assistance:

Security Considerations

File Permissions

# Secure installation
chmod 755 /path/to/binary/mcp-whoisxmlapi
chown $USER /path/to/binary/mcp-whoisxmlapi

# User installation
chmod 755 ~/bin/mcp-whoisxmlapi

Token Security

  • Never hardcode tokens in configuration files
  • Use environment variables for token storage
  • Secure file permissions on configuration files containing tokens
  • Regular token rotation for enhanced security

Verification

# Verify binary integrity (if checksums are provided)
sha256sum mcp-whoisxmlapi
# Compare with published checksums

# Check for tampering
ls -la mcp-whoisxmlapi
file mcp-whoisxmlapi

Integration Examples

Custom Wrapper Script

#!/bin/bash
# mcp-wrapper.sh

# Set default environment
export WHOISXMLAPI_TOKEN="${WHOISXMLAPI_TOKEN:-your-default-token}"
export WHOISXMLAPI_HTTP_DEBUG="${WHOISXMLAPI_HTTP_DEBUG:-/tmp/mcp-debug.log}"

# Run with custom defaults
exec /usr/local/bin/mcp-whoisxmlapi \
  --timeout 30s \
  --disabled-tools threat_intelligence \
  "$@"

Systemd Service (Linux)

# /etc/systemd/system/mcp-whoisxmlapi.service
[Unit]
Description=WhoisXML API MCP Server
After=network.target

[Service]
Type=simple
User=mcp
Group=mcp
WorkingDirectory=/opt/mcp
ExecStart=/usr/local/bin/mcp-whoisxmlapi --http --http-port 3000
Environment=WHOISXMLAPI_TOKEN=your-token-here
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Next Steps

Now that you have the binary installed and configured:

  1. Configure your AI client - See AI Client Configuration
  2. Explore available tools - Check the Tools Reference
  3. Learn about advanced features - Review Server Configuration
  4. Set up monitoring - Enable HTTP Debugging if needed
Last Updated: