# Porkbun Domain Availability MCP Server

A Model Context Protocol (MCP) server that provides tools to check domain availability using the Porkbun API v3.

## Features

- **Single Domain Check**: Check the availability of a single domain name
- **Bulk Domain Check**: Check availability of multiple domains (up to 10 at once)
- **Rate Limiting**: Respects Porkbun's rate limits with built-in delays
- **Error Handling**: Comprehensive error handling with detailed messages

## Tools

### 1. `check_domain_availability`
Checks the availability of a single domain name and returns detailed pricing information.

**Parameters**:
- `domain` (string): The domain name to check for availability

**Returns**: 
- Domain availability status
- Pricing information
- Premium domain status
- First-year promotions
- Renewal and transfer pricing
- Rate limit information

### 2. `bulk_check_domains_availability`
⚠️ **WARNING**: Checks the availability of multiple domain names at once. Due to Porkbun API rate limits (1 check per 10 seconds), this tool has a very long runtime. For example: 5 domains = ~50 seconds, 10 domains = ~100 seconds (1.7 minutes). The bulk tool provides better user experience and consolidated results compared to making multiple single domain check calls.

**Parameters**:
- `domains` (array): Array of domain names to check (maximum 10)

**Returns**: 
- Bulk results with availability status for each domain
- Pricing information for available domains
- Individual error messages for failed checks

## Prerequisites

- [Node.js](https://nodejs.org/) (v18 or later recommended)
- Porkbun API credentials ([generate here](https://porkbun.com/account/api))

## Setup

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure API Credentials

Set your Porkbun API credentials using environment variables or a `.env` file:

#### Option A: Environment Variables
```bash
export PORKBUN_API_KEY="your_api_key"
export PORKBUN_SECRET_API_KEY="your_secret_key"
```

#### Option B: Create a .env file
Create a `.env` file in the project root directory:
```
PORKBUN_API_KEY=your_api_key
PORKBUN_SECRET_API_KEY=your_secret_key
```

#### Option C: Custom .env Location
Pass a custom path when running the server:
```bash
node build/index.js --dotenv-path /path/to/your/.env
```

## Building

Compile the TypeScript code:
```bash
npm run build
```

This creates the executable JavaScript file in the `build/` directory.

## Running the Server

### Standard Start
```bash
npm start
```

### Custom .env Path
```bash
node build/index.js --dotenv-path /path/to/your/.env
```

### Development Mode
```bash
npm run dev
```

The server communicates using the MCP `stdio` transport (standard input/output).

## Usage with Claude Desktop

To use this server with Claude Desktop, add the following configuration to the "mcpServers" section of your `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "porkbun-domain-availability": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-porkbun-domain-availability/build/index.js",
        "--dotenv-path",
        "/absolute/path/to/mcp-porkbun-domain-availability/.env"
      ]
    }
  }
}
```

Replace the placeholder paths with the actual absolute paths on your system. Save the configuration file and restart Claude Desktop.

## API Information

This server uses the Porkbun API v3. For more information about the API:

- [Porkbun API Documentation](https://porkbun.com/api/json/v3/documentation)
- [Domain Check Endpoint](https://porkbun.com/api/json/v3/documentation#Domain%20Check)

## Rate Limiting

The Porkbun API has rate limits for domain checks. This server:
- Implements automatic delays between requests (10 second)
- Limits bulk checks to 10 domains maximum
- Provides rate limit information in responses

## Error Handling

The server provides detailed error messages for:
- Missing or invalid API credentials
- Network connectivity issues
- API rate limit violations
- Invalid domain names
- Server errors

## License

MIT License - see project repository for details.