Content
# Hope Domain MCP Server
[中文版文档](./README_ZH.md) | [English Doc](./README.md)
[](https://www.npmjs.com/package/hopedomain-mcp)
[](https://www.npmjs.com/package/hopedomain-mcp)
[](https://github.com/HopeDomain/whois-mcp/blob/main/LICENSE)
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)
[](https://cursor.com/install-mcp?name=hopedomain-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJob3BlZG9tYWluLW1jcEBsYXRlc3QiXSwiZW52Ijp7IkhPUEVfRE9NQUlOX0FQSV9LRVkiOiJzay15b3VyX2FwaV9rZXlfaGVyZSAoZ2V0IGl0IGZyb20gaHR0cHM6Ly9ob3BlZG9tYWluLmNvbS9hcGkta2V5cykifX0K)
**🎯 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)
```json
{
"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:**
```bash
git clone https://github.com/HopeDomain/whois-mcp.git
cd whois-mcp
```
2. **Install dependencies:**
```bash
npm install
```
3. **Build the project:**
```bash
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](https://hopedomain.com) to register/login
2. Go to [Console](https://hopedomain.com/api-keys) → **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:**
```bash
export HOPE_DOMAIN_API_KEY="sk-your_actual_api_key_here"
```
**Or set directly in configuration file:**
```json
{
"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**
```bash
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**
```env
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)
```json
{
"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
```json
{
"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
```json
{
"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
```typescript
whois_single(domain: string)
```
Query WHOIS information for a single domain (free).
#### Batch Domain WHOIS Query
```typescript
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
```typescript
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
```typescript
get_user_credits()
```
Get current user credit balance and status.
## 📝 Examples
### Basic WHOIS Query
```typescript
// Query a single domain
const result = await whois_single("example.com");
console.log(result);
```
### Batch WHOIS Query
```typescript
// Query multiple domains
const domains = ["example.com", "google.com", "github.com"];
const results = await whois_batch(domains);
console.log(results);
```
### AI Domain Recommendations
```typescript
// 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
```typescript
// 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](LICENSE) file for details.
## 🔗 Links
- 🌐 [Official Website](https://hopedomain.com)
- 📚 [API Documentation](https://hopedomain.com/docs)
- 🔑 [API Keys](https://hopedomain.com/api-keys)
- 💬 [Support](https://hopedomain.com/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.
