npx Installation

Running via npx provides the easiest setup for Node.js developers and CLI-based AI tools. Using npx eliminates package management overhead, automatically runs the latest version, and integrates seamlessly with Node.js workflows.

Why Choose npx?

  • No installation required - Run directly without downloading or storing packages
  • Always latest version - Automatically fetches and runs the most current release
  • Platform detection - Automatically downloads the correct binary for your system
  • CLI integration - Perfect for command-line AI tools and development workflows
  • No Docker required - Direct execution on your system
  • Zero maintenance - No updates, uninstalls, or version management needed

Prerequisites

Check Node.js Version

You can verify the version of Node.js you have installed by running the following commands:

node --version  # Should show v22.0.0 or higher
npm --version   # Should show 8.0.0 or higher

If you need to install or update Node.js, see our Node.js Installation Guide.

Running with npx

Use npx to run the WhoisXML API MCP Server directly without installation:

npx -y @whoisxmlapidotcom/mcp-whoisxmlapi@latest --help

Always the latest version

The @latest tag ensures you always run the most current version with the latest features and bug fixes. No version management required!

Configure Your AI Client

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

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": [
        "-y",
        "@whoisxmlapidotcom/mcp-whoisxmlapi@latest"
      ],
      "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

For most MCP clients:

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

Advanced Configuration

With debugging and custom options:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": [
        "-y",
        "@whoisxmlapidotcom/mcp-whoisxmlapi@latest",
        "--timeout", "30s",
        "--disabled-tools", "threat_intelligence"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here",
        "WHOISXMLAPI_HTTP_DEBUG": "/tmp/whoisxmlapi-debug.log",
        "WHOISXMLAPI_DISABLED_TOOLS": "reverse_whois"
      }
    }
  }
}

HTTP Server Mode

To use HTTP server mode, you need to add the --http and --http-port flags to the command, then instruct your AI client to use the HTTP server mode:

export WHOISXMLAPI_TOKEN="your-api-token-here"
npx -y @whoisxmlapidotcom/mcp-whoisxmlapi@latest --http --http-port 3000

Then instruct your AI client to use the HTTP server mode:

{
  "mcpServers": {
    "whoisxmlapi": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

The configuration is quite minimal in this mode, since most of the options are passed as flags to the original npx command.

HTTP Server Mode supports multiple clients

HTTP server mode uses streamable HTTP transport that automatically handles both direct HTTP responses and SSE streaming. This allows multiple clients to connect to the same server, which is useful for web-based applications or multiple AI clients.

All clients will share the same API key to access WhoisXMLAPI services.

Environment Variables

Set these environment variables for configuration:

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

Version Management with npx

npx automatically handles version management - no manual updates needed!

# Always uses latest version automatically
npx @whoisxmlapidotcom/mcp-whoisxmlapi@latest --help

# Force fresh download if needed
npx --yes @whoisxmlapidotcom/mcp-whoisxmlapi --help

If you need to run a specific version, you can specify it:

npx @whoisxmlapidotcom/mcp-whoisxmlapi@1.2.3 --help

For all available versions, check the npm registry.

Debugging and Logging

Enable HTTP Debugging

Set the debug environment variable. If you're using HTTP server mode, you can set the debug environment variable in the client configuration:

export WHOISXMLAPI_HTTP_DEBUG=/tmp/whoisxmlapi-debug.log
export WHOISXMLAPI_TOKEN=your-token
npx @whoisxmlapidotcom/mcp-whoisxmlapi@latest --http --http-port 3000

In client configuration:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": [
        "-y",
        "@whoisxmlapidotcom/mcp-whoisxmlapi@latest"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-token",
        "WHOISXMLAPI_HTTP_DEBUG": "/tmp/debug.log"
      }
    }
  }
}

Viewing Logs

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

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

Platform-Specific Notes

macOS

  • Ensure any file permissions are correct for the log file
  • Ensure the log file is writable by the user running the server

Windows

  • Some Windows users may need to use PowerShell instead of Command Prompt
  • Make sure paths to log files are correctly escaped, especially when setting them up via environment variables:
    {
  "mcpServers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": [
        "-y",
        "@whoisxmlapidotcom/mcp-whoisxmlapi@latest"
      ],
      "env": {
        "WHOISXMLAPI_HTTP_DEBUG": "C:\\tmp\\debug.log"
      }
    }
  }
}

Linux

  • Ensure any file permissions are correct for the log file
  • Ensure the log file is writable by the user running the server

Troubleshooting

Common Issues

"need to install the following packages: @whoisxmlapidotcom/mcp-whoisxmlapi"

This is normal behavior for npx - it's fetching the latest version to run. This message appears when:

  • Running the package for the first time
  • A new version is available since the last run

You can automatically accept this by using the -y flag:

npx -y @whoisxmlapidotcom/mcp-whoisxmlapi --help

Or in your client configuration:

{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": [
        "-y",
        "@whoisxmlapidotcom/mcp-whoisxmlapi@latest"
      ],
      "env": {
        "WHOISXMLAPI_HTTP_DEBUG": "/tmp/debug.log"
      }
    }
  }
}

Permission Denied

"Permission denied" (macOS/Linux)

# npx avoids permission issues entirely
npx @whoisxmlapidotcom/mcp-whoisxmlapi --help

# This is one of the main benefits of using npx!

"Node.js version incompatible"

# Check Node.js version
node --version

# Update Node.js
# See Node.js Installation Guide for platform-specific instructions

Getting Help

For more troubleshooting assistance:

Verification

Test that npx can run the server correctly:

# Test running the server directly
npx @whoisxmlapidotcom/mcp-whoisxmlapi --help

# Test with your API token
WHOISXMLAPI_TOKEN=your-token npx @whoisxmlapidotcom/mcp-whoisxmlapi --help

If you see the help output, npx is working correctly!

Next Steps

Now that you have npx setup configured:

  1. Configure your AI client - See AI Client Configuration for detailed setup instructions
  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: