@whoisxmlapidotcom/mcp-whoisxmlapi/README.md

A MCP server for the WhoisXML API

# MCP Server `mcp-whoisxmlapi`

`mcp-whoisxmlapi` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that provides AI tools access to the WhoisXMLAPI in a secure and scalable way.

For full documentation, see [the MCP Server documentation](https://mcp-whoisxmlapi.pages.dev/).

## Features

- **Token-based Authentication**: Secure API access using bearer tokens configured via environment variables
- **SSE Support**: Run as an HTTP server with Server-Sent Events (SSE) for web-based integrations
- **Timeout Control**: Configurable request timeouts

## Installation

### Option 1: Docker (Recommended)

You can run `mcp-whoisxmlapi` directly with Docker without installing the binary:

```json
{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "WHOISXMLAPI_TOKEN",
        "whoisxmlapidotcom/mcp-whoisxmlapi:latest"
        // Add custom options if needed:
        // "--timeout=30s"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

### Option 2: npm

Install via npm for convenience:

```bash
# Install globally
npm install -g @whoisxmlapidotcom/mcp-whoisxmlapi

# Or install locally in your project
npm install @whoisxmlapidotcom/mcp-whoisxmlapi
```

#### Editor Configuration with npm

If installed globally via npm:

```json
{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "mcp-whoisxmlapi",
      "args": [
        // Uncomment and modify as needed:
        // "--timeout=30s"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

If installed locally in a project:

```json
{
  "mcpServers": {
    "whoisxmlapi": {
      "command": "npx",
      "args": [
        "@whoisxmlapidotcom/mcp-whoisxmlapi"
        // Add custom options if needed:
        // "--timeout=30s"
      ],
      "env": {
        "WHOISXMLAPI_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

### Option 3: Binary Download

You can also download the appropriate binary for your operating system from the [Downloads](https://mcp-whoisxmlapi.pages.dev/downloads) page and provide the full path to the binary (e.g., `/path/to/mcp-whoisxmlapi`) in your editor configuration.

### Docker

The MCP server is available as a Docker image using `stdio` to communicate:

```bash
docker pull whoisxmlapidotcom/mcp-whoisxmlapi:latest
docker run --rm -e WHOISXMLAPI_TOKEN=your-token whoisxmlapidotcom/mcp-whoisxmlapi:latest
```

For SSE mode with Docker, expose the SSE port (default `3000`):

```bash
docker run --rm -p 3000:3000 -e WHOISXMLAPI_TOKEN=your-token whoisxmlapidotcom/mcp-whoisxmlapi:latest --sse --sse-port 3000
```

The configuration for SSE mode changes slightly in your editor's settings -- and note you'll need to run the Docker container in SSE mode for this to work prior to adding the configuration to your editor's or AI client settings:

```json
{
  "mcpServers": {
    "whoisxmlapi": {
      "url": "http://localhost:3000"
    }
  }
}
```

Do note that some MCP Clients will not support non-HTTPS endpoints.

With this configuration you can use the same MCP server for multiple AI clients at once: normally, AI clients will create multiple instances of an MCP server.

## Environment Variables

- `WHOISXMLAPI_TOKEN`: Required. The API token for authenticating with the WhoisXMLAPI service.

## Running Modes

### Standard (stdio) Mode

By default, `mcp-whoisxmlapi` runs in stdio mode, which is suitable for integration with editors and other tools that communicate via standard input/output.

```bash
export WHOISXMLAPI_TOKEN=your-token-here
mcp-whoisxmlapi
```

### Server-Sent Events (SSE) Mode

Alternatively, you can run `mcp-whoisxmlapi` as an HTTP server with SSE support for web-based integrations:

```bash
export WHOISXMLAPI_TOKEN=your-token-here
mcp-whoisxmlapi --sse --sse-port=3000
```

In SSE mode, the server will listen on the specified port (default: 3000) and provide the same MCP tools over HTTP using Server-Sent Events. This is useful for web applications or environments where stdio communication isn't practical.

**Available SSE Options:**
- `--sse`: Enable SSE server mode
- `--sse-port=PORT`: Specify the port to listen on (default: 3000)