# MCP Domain Checker Price
**Model Context Protocol server for domain pricing and affiliate purchase links from Joker.com**
This MCP server provides domain registration pricing via the official [Joker.com DMAPI](https://dmapi.joker.com) and generates affiliate purchase links with automatic browser integration.
[](https://opensource.org/licenses/MIT)
[](https://github.com/3viky/mcp-domain-checker-price)
## Features
- ā” **Two-Tier Pricing System** - Static JSON (default, zero-config) + optional real-time API
- š **Zero Configuration** - Works immediately with bundled pricing data
- š° **Comprehensive Pricing** - Registration, renewal, and transfer prices
- š¾ **Smart Caching** - 6-hour TTL cache reduces API load
- š **Affiliate Links** - Optional affiliate tracking for purchase links
- š **Browser Integration** - Works with mcp-opener for automatic Firefox opening
- š **Optional Real-Time Pricing** - Use Joker.com DMAPI for current prices (requires credentials)
- š¦ **Lightweight** - No browser automation, pure API integration
## Quick Start
### 1. Installation
```bash
# Navigate to package directory
cd /var/home/viky/Code/packages/src/@mcp/mcp-domain-checker-price
# Run setup script
./setup.sh
```
### 2. Configuration (Optional)
The server works immediately with built-in pricing data. Configuration is only needed for:
- Real-time pricing updates (requires Joker.com credentials)
- Affiliate commission tracking
```bash
# Copy environment template (optional)
cp .env.example .env
# Edit .env with your credentials (optional)
nano .env
```
**Optional - For Real-Time Pricing:** Set Joker.com authentication:
- **Option A (Recommended):** API Key from [Joker.com ā My Profile ā API Access Keys](https://joker.com/user/profile)
- **Option B:** Username + Password
**Optional - For Affiliate Tracking:** Set affiliate ID for commission tracking
### 3. Add to Claude Code
Add to `.claude/settings.json` or global MCP configuration:
```json
{
"mcpServers": {
"domain-checker-price": {
"command": "node",
"args": ["/var/home/viky/Code/packages/src/@mcp/mcp-domain-checker-price/dist/index.js"]
}
}
}
```
## Available Tools
### 1. `get_version`
Get server version and capabilities
**Parameters:** None
**Example:**
```javascript
mcp__mcp-domain-checker-price__get_version()
```
---
### 2. `get_domain_pricing`
Fetch domain pricing from Joker.com (static data by default, real-time DMAPI optional)
**Parameters:**
- `domain` (string, required) - Domain name to check (e.g., "example.com")
- `force_refresh` (boolean, optional) - Bypass cache, default: false
- `use_api` (boolean, optional) - Use real-time DMAPI instead of static data (requires credentials), default: false
**Response:**
```json
{
"domain": "example.com",
"pricing": {
"registration_1yr": 12.36,
"renewal_1yr": 14.50,
"transfer": 12.36,
"currency": "EUR"
},
"special_offers": [
{
"description": "create discount until 12/31/2024",
"discount_price": 10.00
}
],
"source_url": "https://dmapi.joker.com/request/query-price-list",
"last_updated": "2025-12-11T14:30:00.000Z",
"from_cache": false
}
```
**Example:**
```javascript
// Static pricing (default, fast, no auth required)
mcp__mcp-domain-checker-price__get_domain_pricing({ domain: "myapp.com" })
// Real-time pricing (requires Joker.com credentials)
mcp__mcp-domain-checker-price__get_domain_pricing({
domain: "myapp.com",
use_api: true
})
// Force refresh from cache
mcp__mcp-domain-checker-price__get_domain_pricing({
domain: "myapp.com",
force_refresh: true
})
```
---
### 3. `open_purchase_link`
Generate purchase links with optional affiliate tracking
**Parameters:**
- `domain` (string) - Single domain to purchase *(mutually exclusive with domains)*
- `domains` (array) - Multiple domains to purchase *(mutually exclusive with domain)*
- `open_all` (boolean, optional) - Open all URLs (true) or just first (false), default: false
**Response (Single Domain):**
```json
{
"message": "Purchase link generated",
"link": {
"registrar": "joker",
"domain": "example.com",
"url": "https://joker.com/domain/registration?domain=example.com&aff=YOUR_ID",
"is_affiliate": true,
"price_estimate": 12.36,
"currency": "EUR"
},
"suggestion": "Use mcp__opener__open_browser to open this URL in Firefox"
}
```
**Response (Multiple Domains):**
```json
{
"message": "Purchase links generated for 3 domain(s)",
"links": [...],
"urls_to_open": ["https://joker.com/..."],
"open_all": false,
"total_estimate": {
"total": 37.08,
"currency": "EUR",
"domains_with_pricing": 3,
"domains_without_pricing": 0
},
"suggestion": "Use mcp__opener__open_browser to open 1 URL(s) in Firefox"
}
```
**Examples:**
```javascript
// Single domain
mcp__mcp-domain-checker-price__open_purchase_link({ domain: "myapp.com" })
// Multiple domains (open first only)
mcp__mcp-domain-checker-price__open_purchase_link({
domains: ["app.com", "app.io", "app.dev"]
})
// Multiple domains (open all in separate tabs)
mcp__mcp-domain-checker-price__open_purchase_link({
domains: ["app.com", "app.io", "app.dev"],
open_all: true
})
```
## Integration with Opener MCP
**Recommended Workflow:**
```javascript
// Step 1: Get pricing
const pricing = await mcp__mcp-domain-checker-price__get_domain_pricing({
domain: "myapp.com"
});
// Step 2: Generate purchase link
const purchase = await mcp__mcp-domain-checker-price__open_purchase_link({
domain: "myapp.com"
});
// Step 3: Open in Firefox
await mcp__opener__open_browser({
url: purchase.link.url
});
```
## Pricing System
### Two-Tier Architecture
**Static Pricing (Default):**
- ā
Zero configuration required
- ā
Instant response (no API calls)
- ā
No authentication needed
- ā ļø Data may be slightly outdated (refresh with `./update-pricing.sh`)
- š Covers 10+ common TLDs by default (com, net, org, io, app, dev, etc.)
**Real-Time DMAPI (Optional):**
- ā
Current prices directly from Joker.com
- ā
Automatically updated
- ā ļø Requires Joker.com credentials
- ā ļø Slower (API call per request)
### Updating Static Pricing
```bash
# Option 1: Use the shell script (recommended)
./update-pricing.sh
# Option 2: Use pnpm script
pnpm fetch-pricing
```
This fetches current pricing from Joker.com DMAPI and updates `data/pricing.json`. The MCP server will automatically use the updated data on next restart.
**Note:** Requires Joker.com credentials configured in `.env`
## Configuration Reference
### Environment Variables
```bash
# ============================================================================
# Joker.com DMAPI Authentication (OPTIONAL - for real-time pricing)
# ============================================================================
# Option 1: API Key (Recommended)
# Create at: Joker.com ā My Profile ā Manage API access keys
MCP_JOKER_API_KEY="your-api-key-here"
# Option 2: Username & Password (Alternative)
MCP_JOKER_USERNAME="your-username"
MCP_JOKER_PASSWORD="your-password"
# ============================================================================
# Joker.com Affiliate Configuration (OPTIONAL - for commission tracking)
# ============================================================================
# Sign up: https://joker.com/affiliate
# Leave empty for non-affiliate links
MCP_AFFILIATE_JOKER_ID="your-affiliate-id"
# ============================================================================
# Pricing Cache Configuration
# ============================================================================
# Cache duration in hours (default: 6)
# Set to 0 to disable caching (not recommended)
MCP_DOMAIN_PRICING_CACHE_TTL_HOURS=6
```
### API Key vs Username/Password
| Method | Security | Features | Recommended |
|--------|----------|----------|-------------|
| **API Key** | ā
Higher (revocable) | Can be read-only | ā
Yes |
| **Username/Password** | ā ļø Lower | Full account access | ā ļø Only if needed |
**API Key Advantages:**
- Don't expose main credentials
- Can be restricted to read-only mode
- Can be revoked without changing password
- Can create multiple keys for different uses
## Architecture
```
mcp-domain-checker-price/
āāā src/
ā āāā index.ts # MCP server entry point
ā āāā dmapi-client.ts # Joker.com API authentication
ā āāā pricing-fetcher.ts # Two-tier pricing system
ā āāā static-pricing.ts # Static JSON loader (default)
ā āāā affiliate-links.ts # Purchase URL generation
ā āāā price-cache.ts # LRU cache with TTL
ā āāā tools/
ā āāā get-version.ts # Version info tool
ā āāā get-domain-pricing.ts # Pricing tool
ā āāā open-purchase-link.ts # Purchase link tool
āāā scripts/
ā āāā fetch-pricing.ts # DMAPI pricing fetcher
āāā data/
ā āāā pricing.json # Static pricing database (optional)
āāā dist/ # Compiled JavaScript
āāā package.json
āāā tsconfig.json
āāā .env.example # Configuration template
āāā setup.sh # Setup script
āāā update-pricing.sh # Update static pricing data
```
## How It Works
### Pricing Fetch Flow (Default - Static)
1. Check cache for domain pricing
2. If cache miss ā Load from `data/pricing.json` (or use bundled defaults)
3. Extract pricing for domain's TLD
4. Cache result for 6 hours
5. Return pricing data
### Pricing Fetch Flow (Real-Time - use_api=true)
1. Check if DMAPI credentials configured
2. If not configured ā Fall back to static pricing
3. Authenticate with Joker.com DMAPI (session valid 1 hour)
4. Call `query-price-list` API
5. Parse TSV response (tab-separated values)
6. Extract pricing for domain's TLD
7. Cache result for 6 hours
8. Return pricing data
### Affiliate Link Flow
1. Load affiliate ID from environment
2. Generate Joker.com registration URL
3. Append `&aff=YOUR_ID` if affiliate configured
4. Return URL with price estimate (if available)
## Troubleshooting
### ā "No pricing data found for TLD .xyz"
**Solution:**
- Using static pricing: TLD not in bundled data. Run `./update-pricing.sh` to fetch all Joker.com TLDs
- Using real-time pricing: TLD might not be available through Joker.com or not in your reseller account's price list
### ā ļø "DMAPI requested but not configured, using static pricing"
**Info:** You requested `use_api=true` but credentials not set. Server automatically falls back to static pricing. To use real-time pricing, set `MCP_JOKER_API_KEY` or `MCP_JOKER_USERNAME` + `MCP_JOKER_PASSWORD` in `.env`
### ā "DMAPI login failed (HTTP 401)"
**Solution:** Check credentials - API key may be expired or invalid
### ā ļø Cache always returns `from_cache: false`
**Solution:** Check `MCP_DOMAIN_PRICING_CACHE_TTL_HOURS` is > 0 in `.env`
### ā ļø Affiliate links show `is_affiliate: false`
**Solution:** Set `MCP_AFFILIATE_JOKER_ID` in `.env` and restart server
## Development
```bash
# Install dependencies
pnpm install
# Build TypeScript
pnpm build
# Watch mode
pnpm dev
# Update static pricing data (requires .env)
./update-pricing.sh
# Run tests (if available)
pnpm test
```
## API Reference
### Joker.com DMAPI Endpoints Used
- **`/request/login`** - Authentication
- **`/request/query-price-list`** - Complete TLD pricing list
**Documentation:** https://dmapi.joker.com/docs/
## License
MIT Ā© Victoria Lackey
## Sources
- [Joker.com DMAPI Documentation](https://dmapi.joker.com/docs/)
- [Joker.com Domain Management API](https://dmapi.joker.com/)
- [Joker.com FAQ - DMAPI](https://joker.com/faq/books/reseller-documentation-en/chapter/dmapi)
## Contributing
This package is part of the [@3viky/mcp](https://github.com/3viky) monorepo ecosystem.
For issues and contributions, please visit the [GitHub repository](https://github.com/3viky/mcp-domain-checker-price).
---
**Built with** [Model Context Protocol](https://modelcontextprotocol.io/) | **Powered by** [Joker.com DMAPI](https://dmapi.joker.com/)
