MCP Domain Availability Server

A Model Context Protocol (MCP) server for checking domain availability and pricing using the GoDaddy OTE (Operational Test Environment) API.

Features

Check domain availability and pricing via GoDaddy OTE sandbox
Support for multiple TLD suffixes
Fast and Full check modes
Support for bulk domain checking
Rate limiting (60 calls per minute)
Normalized pricing in dollars with 2 decimal places
Consistent field naming and data structures
Period normalization (stored in months, displayed in years)

Installation

Using uv (Recommended)

# Install dependencies
uv add "mcp[cli]"

# Run with MCP Inspector for testing
DOMAIN_API_KEY="your-key:your-secret" mcp dev domain_availability/server.py

Manual Installation

pip install -e .

Configuration

Environment Variables

DOMAIN_API_KEY: Your GoDaddy OTE API credentials in format "key:secret" (required)

Note: The server uses GoDaddy OTE (sandbox) API by default: https://api.ote-godaddy.com

GoDaddy OTE Setup

Sign up for GoDaddy Developer account
Get OTE (sandbox) API credentials
Set the environment variable: DOMAIN_API_KEY="your-ote-key:your-ote-secret"

MCP Configuration

Add this to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "domain-availability": {
      "command": "uv",
      "args": ["run", "mcp-domain-availability"],
      "env": {
        "DOMAIN_API_KEY": "your-ote-key:your-ote-secret"
      }
    }
  }
}

Usage

Development & Testing

# Start MCP Inspector for testing
DOMAIN_API_KEY="your-key:your-secret" mcp dev domain_availability/server.py

This will start the MCP Inspector at http://localhost:6274 for interactive testing.

Tools Available

The server provides one tool: check_domain_availability

Parameters

Option 1: Direct domain list

domains: Array of domain names to check (e.g., ["example.com", "example.org"])

Option 2: Base name with TLD suffixes

base_name: Base domain name (e.g., "example")
tld_suffixes: Array of TLD suffixes (e.g., [".com", ".org", ".net", ".io"])

Optional

checkType: "FAST" or "FULL" (default: "FAST")
- FAST: Optimized for speed
- FULL: Optimized for accuracy

Examples

Check specific domains

{
  "domains": ["example.com", "example.org", "example.net"],
  "checkType": "FAST"
}

Check base name with multiple TLDs

{
  "base_name": "myawesomesite",
  "tld_suffixes": [".com", ".org", ".net", ".io", ".dev", ".app"],
  "checkType": "FULL"
}

Response Format

Text Response:

Domain Availability Check Results:

✅ AVAILABLE DOMAINS:
  • example.com - $12.99 USD for 1 year (Definitive)
  • example.org - $8.99 USD for 2 years (Preliminary)

❌ UNAVAILABLE DOMAINS:
  • example.net - Not available - Domain already registered

JSON Response (normalized fields):

{
  "domains": [
    {
      "domain_name": "example.com",
      "is_available": true,
      "price_dollars": 12.99,
      "currency_code": "USD",
      "is_definitive": true,
      "registration_period_months": 12
    },
    {
      "domain_name": "example.net",
      "is_available": false,
      "price_dollars": 0.00,
      "currency_code": "USD",
      "is_definitive": true,
      "registration_period_months": 12,
      "error_message": "Domain already registered"
    }
  ],
  "errors": []
}

Data Normalization

Price Normalization

Input: GoDaddy API returns prices in micro-units (1/1,000,000 of currency)
Output: Converted to dollars with 2 decimal places
Example: 12000000 micro-units → $12.00 USD

Period Normalization

Storage: Period stored in months for consistency
Display: Converted to years for user-friendly display
Example: 12 months → "1 year", 24 months → "2 years"

Field Naming

Consistent, explicit field names:

domain_name (instead of domain)
is_available (instead of available)
price_dollars (instead of price)
currency_code (instead of currency)
is_definitive (instead of definitive)
registration_period_months (instead of period)
error_message (instead of error)

API Integration

This server integrates with GoDaddy OTE API:

Base URL: https://api.ote-godaddy.com
Endpoint: GET /v1/domains/available?domain={domain}
Headers: Authorization: sso-key {key}:{secret}
Rate Limit: 60 requests per minute

Authentication Format

Authorization: sso-key your-key:your-secret

Error Handling

The server handles various error conditions:

Missing API key
Invalid domains
API rate limits (429) - with retry guidance
Partial responses (203)
Authentication errors (401, 403)
Server errors (500)
Network timeouts

Development

Setup Development Environment

# Clone and setup
git clone <repository>
cd mcp-free-domain
uv add "mcp[cli]"

# Run tests
pytest

# Start development server
DOMAIN_API_KEY="test-key:test-secret" mcp dev domain_availability/server.py

Testing with MCP Inspector

Set your OTE credentials: DOMAIN_API_KEY="your-key:your-secret"
Run: mcp dev domain_availability/server.py
Open browser at http://localhost:6274
Use the session token displayed in terminal if prompted
Test the check_domain_availability tool

License

MIT License

Support

For issues and questions, please create an issue in the repository.