README.md•5.61 kB
# 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)
```bash
# 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
```bash
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
1. Sign up for GoDaddy Developer account
2. Get OTE (sandbox) API credentials
3. 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`):
```json
{
"mcpServers": {
"domain-availability": {
"command": "uv",
"args": ["run", "mcp-domain-availability"],
"env": {
"DOMAIN_API_KEY": "your-ote-key:your-ote-secret"
}
}
}
}
```
## Usage
### Development & Testing
```bash
# 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
```json
{
"domains": ["example.com", "example.org", "example.net"],
"checkType": "FAST"
}
```
#### Check base name with multiple TLDs
```json
{
"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):**
```json
{
"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
```bash
# 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
1. Set your OTE credentials: `DOMAIN_API_KEY="your-key:your-secret"`
2. Run: `mcp dev domain_availability/server.py`
3. Open browser at `http://localhost:6274`
4. Use the session token displayed in terminal if prompted
5. Test the `check_domain_availability` tool
## License
MIT License
## Support
For issues and questions, please create an issue in the repository.