# 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.
