Domain Checker Server

A Model Context Protocol (MCP) server that checks domain name availability using the WhoisJSON API.

Features

• Check if domain names are available for registration
• Get detailed registration information for registered domains
• Easy-to-use HTTP API for testing
• Built with TypeScript for type safety and readability

API Limits

• Rate Limit: 20 requests per minute
• Monthly Limit: 1000 requests per month

Setup

Initial Setup

1. Install dependencies:

npm install

2. Create a .env file with your WhoisJSON API key:

WHOISJSON_API_KEY=your-api-key-here
PORT=6005

3. Build the project:

npm run build

Usage

Option 1: Testing with HTTP Server

The HTTP mode is for testing only - it runs a REST API on port 6005 so you can verify everything works.

Start the HTTP server:

npm run start:http

Test it:

# Health check
curl http://localhost:6005/health

# Check a domain
curl http://localhost:6005/check/example.com

Stop the server when done testing (Ctrl+C).

Option 2: Using with Claude Desktop (MCP Mode)

This is the main use case - Claude Desktop will automatically start and manage the server.

Important: MCP mode uses stdio (not HTTP/ports), so there are no port conflicts. Claude starts the server automatically when it launches.

Steps to Configure:

1. Build the project (if not already done):

npm run build

2. Add to Claude Desktop config:
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "domain-checker": {
      "command": "node",
      "args": [
        "/FULL/PATH/TO/domain-checker-mcp/dist/index.js"
      ],
      "env": {
        "WHOISJSON_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Replace the paths:

   • Change /FULL/PATH/TO/domain-checker-mcp to your actual project path
   • Change your-api-key-here to your WhoisJSON API key

4. Restart Claude Desktop

5. Test it: Ask Claude "Is example.com available?"

Moving to a Different Machine

To use this MCP server on another machine:

1. Copy the project to the new machine
2. Install dependencies: npm install
3. Build: npm run build
4. Update Claude Desktop config on the new machine with the correct path and API key
5. Restart Claude Desktop

How It Works: HTTP vs MCP Mode

• HTTP Mode (npm run start:http): Uses port 6005, for testing with curl/browser
• MCP Mode (npm start or run by Claude): Uses stdio (no ports), for AI integration

These are completely separate - MCP mode does NOT use HTTP or ports, so they never conflict. Claude Desktop automatically starts the server in MCP mode when it launches.

MCP Tool: check_domain

Input:

• domain (string, required): The domain name to check (e.g., "example.com", "mysite.org")

Output:

If domain is available:

{
  "available": true,
  "registered": false,
  "domain": "myawesomesite123.com"
}

If domain is registered:

{
  "available": false,
  "registered": true,
  "domain": "EXAMPLE.COM",
  "created": "1995-08-14 04:00:00",
  "expires": "2026-08-13 04:00:00",
  "registrar": "RESERVED-Internet Assigned Numbers Authority",
  "nameservers": ["elliott.ns.cloudflare.com", "hera.ns.cloudflare.com"],
  "daysUntilExpiry": 125
}

Code Structure

• src/index.ts - Main server code with clear, documented functions
• .env - Environment configuration (API key, port)
• tsconfig.json - TypeScript configuration

Development

Watch mode (auto-restart on changes):

npm run dev

Build:

npm run build

How It Works

1. checkDomainAvailability() - Queries the WhoisJSON API with the domain name
2. createMCPServer() - Sets up the MCP server with the check_domain tool
3. createExpressServer() - Creates an HTTP server for easy testing
4. main() - Entry point that starts either HTTP or MCP mode based on arguments

The code is written to be easy to read and understand, with clear function names, comments, and TypeScript types.