Hope Domain MCP Server

中文版文档 | English Doc

A Model Context Protocol (MCP) server that provides Hope Domain API services, including domain WHOIS queries and AI-driven domain recommendations.

✨ Features

🔍 Domain WHOIS Queries

• Single domain WHOIS queries (free)
• Batch domain WHOIS queries (up to 1000 domains, ≤50 free)

🤖 AI Domain Recommendations

• AI-driven domain suggestions based on project descriptions
• Generate 1-50 domain recommendations per request

💰 Credit Management

• View current credit balance and account status
• Track usage and recharge history

🚀 Zero Warnings

• Uses Node.js native fetch API
• Zero dependency warnings, clean installation experience

📦 Installation Methods

⚡ Method 1: One-Click Installation (Recommended for Cursor Users)

🎯 Features:

• ⚡ Zero Configuration - Click to use, no manual setup required
• 🔄 Auto Updates - Always uses the latest version
• 🚀 Instant Deployment - No local installation needed
• ✨ Completely Warning-Free - Clean runtime environment

⚙️ Method 2: Standard Configuration (Universal)

NPX Method (Recommended)

{
  "mcpServers": {
    "hopedomain-mcp": {
      "command": "npx",
      "args": ["hopedomain-mcp@latest"],
      "env": {
        "HOPE_DOMAIN_API_KEY": "sk-your_api_key_here"
      }
    }
  }
}

🎯 Features:

• 📦 No Installation Required - Run directly via npx
• 🔄 Auto Updates - @latest ensures the latest version
• 🌐 Cross-Platform Compatible - Supports all MCP clients
• ⚡ Lightweight & Fast - Only requires API key configuration
• ✨ Zero Warning Output - Completely clean runtime experience

Local Development Installation

1. Clone the repository:

   git clone https://github.com/HopeDomain/whois-mcp.git
   cd whois-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

📁 Configuration File Templates

We provide multiple pre-configured templates in the configs/ directory:

• 📄 configs/claude-desktop.json - Claude Desktop standard configuration
• 📄 configs/cursor-mcp.json - Cursor MCP configuration
• 📄 configs/local-dev.json - Local development configuration

Simply copy the corresponding configuration to your MCP client configuration file!

🚀 Quick Start

🎯 Step 1: Choose Installation Method

• Cursor Users → Click the one-click installation button ⚡
• Other Users → Use NPX standard configuration ⚙️

🔑 Step 2: Get API Key

1. Visit Hope Domain Official Website to register/login
2. Go to Console → API Keys page
3. Click the "Create API Key" button
4. Copy the generated API key (format: sk-xxxxxxxxxx)

⚙️ Step 3: Configure API Key

Environment Variable Method:

export HOPE_DOMAIN_API_KEY="sk-your_actual_api_key_here"

Or set directly in configuration file:

{
  "env": {
    "HOPE_DOMAIN_API_KEY": "sk-your_actual_api_key_here"
  }
}

✨ Step 4: Start Using!

Now you can use these powerful tools:

• 🔍 whois_single - Single domain WHOIS query
• 📊 whois_batch - Batch domain queries (up to 1000)
• 🤖 ai_domain_recommend - AI domain recommendations
• 💰 get_user_credits - Account credit query

⚙️ Configuration Guide

🔐 Environment Variable Configuration

Method 1: System Environment Variables

export HOPE_DOMAIN_API_KEY="sk-your_actual_api_key_here"
export HOPE_DOMAIN_BASE_URL="https://hopedomain.com/api"  # Optional, defaults to production API

Method 2: Project .env File

HOPE_DOMAIN_API_KEY=sk-your_actual_api_key_here
HOPE_DOMAIN_BASE_URL=https://hopedomain.com/api

📋 Different Client Configuration Examples

Claude Desktop

📁 Config File: ~/.config/claude/claude_desktop_config.json (Linux/Mac)
📁 Config File: %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "hopedomain-mcp": {
      "command": "npx",
      "args": ["hopedomain-mcp@latest"],
      "env": {
        "HOPE_DOMAIN_API_KEY": "sk-your_actual_api_key_here"
      }
    }
  }
}

Cursor IDE

📁 Config Location: Settings → Extensions → MCP

{
  "mcpServers": {
    "hopedomain-mcp": {
      "command": "npx",
      "args": ["hopedomain-mcp@latest"],
      "env": {
        "HOPE_DOMAIN_API_KEY": "${HOPE_DOMAIN_API_KEY}"
      }
    }
  }
}

Local Development

Use Case: Source code development, debugging, custom modifications

{
  "mcpServers": {
    "hopedomain-mcp": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/whois-mcp",
      "env": {
        "HOPE_DOMAIN_API_KEY": "sk-your_actual_api_key_here",
        "HOPE_DOMAIN_BASE_URL": "https://hopedomain.com/api"
      }
    }
  }
}

🔧 API Reference

WHOIS Queries

Single Domain WHOIS Query

whois_single(domain: string)

Query WHOIS information for a single domain (free).

Batch Domain WHOIS Query

whois_batch(domains: string[], format?: "json")

Query WHOIS information for multiple domains at once (up to 1000 domains, ≤50 free).

AI Domain Recommendations

AI-Powered Domain Recommendations

ai_domain_recommend(description: string, count?: number)

Get AI-powered domain name recommendations based on project description (1-50 recommendations).

Account Management

Get User Credits

get_user_credits()

Get current user credit balance and status.

📝 Examples

Basic WHOIS Query

// Query a single domain
const result = await whois_single("example.com");
console.log(result);

Batch WHOIS Query

// Query multiple domains
const domains = ["example.com", "google.com", "github.com"];
const results = await whois_batch(domains);
console.log(results);

AI Domain Recommendations

// Get domain recommendations for a project
const recommendations = await ai_domain_recommend(
  "A modern e-commerce platform for sustainable products",
  10
);
console.log(recommendations);

Check Account Credits

// Check your account balance
const credits = await get_user_credits();
console.log(credits);

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• 🌐 Official Website
• 📚 API Documentation
• 🔑 API Keys
• 💬 Support

⭐ Support

If you find this project helpful, please give it a star on GitHub! Your support motivates us to continue improving and adding new features.