f5e63c888d
- Production-ready MCP server for Name Cheap API integration - Domain management (registration, renewal, availability checking) - DNS management (records, nameserver configuration) - SSL certificate management and monitoring - Account information and balance checking - Smart identifier resolution for improved UX - Comprehensive error handling with specific exception types - 80%+ test coverage with unit, integration, and MCP tests - CLI and MCP server interfaces - FastMCP 2.10.5+ implementation with full MCP spec compliance 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
470 lines
14 KiB
Markdown
470 lines
14 KiB
Markdown
# MCP Name Cheap
|
|
|
|
[](https://badge.fury.io/py/mcp-namecheap)
|
|
[](https://www.python.org/downloads/)
|
|
[](https://github.com/psf/black)
|
|
[](https://github.com/astral-sh/ruff)
|
|
[](https://github.com/jlowin/fastmcp)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
Production-ready MCP server for comprehensive Name Cheap API integration. Manage domains, DNS records, SSL certificates, and account information through the Model Context Protocol with smart identifier resolution and comprehensive error handling.
|
|
|
|
## ✨ Features
|
|
|
|
### 🌐 Domain Management
|
|
- **Smart Domain Discovery**: Use exact domain names for seamless operations
|
|
- **Domain Registration**: Complete domain registration with contact validation
|
|
- **Domain Renewal**: Extend domain registrations with flexible year options
|
|
- **Availability Checking**: Bulk domain availability verification
|
|
- **Domain Information**: Detailed domain status, expiration, and configuration data
|
|
|
|
### 🔧 DNS Management
|
|
- **Complete DNS Control**: Manage A, AAAA, CNAME, MX, TXT, NS, and SRV records
|
|
- **Nameserver Configuration**: Switch between Name Cheap default and custom nameservers
|
|
- **Record Validation**: Pre-operation validation with helpful error messages
|
|
- **TTL Management**: Configurable Time-To-Live settings for all record types
|
|
|
|
### 🔒 SSL Certificate Management
|
|
- **Certificate Discovery**: Smart certificate lookup by ID, hostname, or type
|
|
- **Certificate Monitoring**: Track expiration dates and status
|
|
- **Comprehensive Details**: Full certificate information including SANs and providers
|
|
|
|
### 👤 Account Management
|
|
- **Account Information**: Complete account details and verification status
|
|
- **Balance Monitoring**: Real-time account balance and available funds
|
|
- **Multi-currency Support**: Handle multiple currency balances
|
|
|
|
### 🛠️ Developer Experience
|
|
- **FastMCP 2.10.5+**: Built on the latest FastMCP with full MCP spec compliance
|
|
- **Smart Identifiers**: Use human-readable names instead of UUIDs
|
|
- **Comprehensive Testing**: 80%+ test coverage with unit, integration, and MCP tests
|
|
- **Type Safety**: Full type hints with mypy validation
|
|
- **Error Handling**: Specific exception types with actionable error messages
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Using pip
|
|
pip install mcp-namecheap
|
|
|
|
# Using uv (recommended)
|
|
uv add mcp-namecheap
|
|
|
|
# Development installation
|
|
git clone https://github.com/your-org/mcp-namecheap
|
|
cd mcp-namecheap
|
|
uv install -e ".[dev]"
|
|
```
|
|
|
|
### Configuration
|
|
|
|
1. **Get Name Cheap API Credentials**:
|
|
- API Key: Name Cheap Account Panel → Profile → Tools → Name Cheap API Access
|
|
- Username: Your Name Cheap account username
|
|
- Client IP: Your server's IP address (must be whitelisted)
|
|
|
|
2. **Environment Setup**:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your credentials
|
|
```
|
|
|
|
```bash
|
|
# .env file
|
|
NAMECHEAP_API_KEY=your_api_key_here
|
|
NAMECHEAP_USERNAME=your_username_here
|
|
NAMECHEAP_CLIENT_IP=your_whitelisted_ip_here
|
|
NAMECHEAP_SANDBOX=true # Use false for production
|
|
```
|
|
|
|
### Running the Server
|
|
|
|
```bash
|
|
# As a module
|
|
python -m mcp_namecheap
|
|
|
|
# Using the installed script
|
|
mcp-namecheap
|
|
|
|
# With custom configuration
|
|
NAMECHEAP_SANDBOX=false mcp-namecheap
|
|
```
|
|
|
|
## 🔧 MCP Client Configuration
|
|
|
|
Add to your MCP client configuration:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"namecheap": {
|
|
"command": "mcp-namecheap",
|
|
"env": {
|
|
"NAMECHEAP_API_KEY": "your_api_key",
|
|
"NAMECHEAP_USERNAME": "your_username",
|
|
"NAMECHEAP_CLIENT_IP": "your_ip",
|
|
"NAMECHEAP_SANDBOX": "true"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 📖 Usage Examples
|
|
|
|
### Domain Operations
|
|
|
|
```python
|
|
# Check domain availability
|
|
await mcp_client.call_tool("check_domain_availability", {
|
|
"domains": ["example.com", "mysite.org", "newdomain.net"]
|
|
})
|
|
|
|
# Register a new domain
|
|
await mcp_client.call_tool("register_domain", {
|
|
"domain_name": "mynewdomain.com",
|
|
"years": 2,
|
|
"contacts": {
|
|
"first_name": "John",
|
|
"last_name": "Doe",
|
|
"address1": "123 Main Street",
|
|
"city": "Anytown",
|
|
"state_province": "CA",
|
|
"postal_code": "12345",
|
|
"country": "US",
|
|
"phone": "+1.5551234567",
|
|
"email_address": "john@example.com"
|
|
}
|
|
})
|
|
|
|
# Get domain information
|
|
await mcp_client.call_tool("get_domain_info", {
|
|
"domain_identifier": "example.com"
|
|
})
|
|
|
|
# Renew domain
|
|
await mcp_client.call_tool("renew_domain", {
|
|
"domain_identifier": "example.com",
|
|
"years": 1
|
|
})
|
|
```
|
|
|
|
### DNS Management
|
|
|
|
```python
|
|
# Get current DNS records
|
|
await mcp_client.call_tool("get_dns_records", {
|
|
"domain_identifier": "example.com"
|
|
})
|
|
|
|
# Set DNS records
|
|
await mcp_client.call_tool("set_dns_records", {
|
|
"domain_identifier": "example.com",
|
|
"records": [
|
|
{
|
|
"hostname": "@",
|
|
"record_type": "A",
|
|
"address": "192.168.1.100",
|
|
"ttl": 3600
|
|
},
|
|
{
|
|
"hostname": "www",
|
|
"record_type": "CNAME",
|
|
"address": "example.com",
|
|
"ttl": 3600
|
|
},
|
|
{
|
|
"hostname": "mail",
|
|
"record_type": "MX",
|
|
"address": "mail.example.com",
|
|
"ttl": 3600,
|
|
"mx_pref": 10
|
|
}
|
|
]
|
|
})
|
|
|
|
# Set custom nameservers
|
|
await mcp_client.call_tool("set_custom_nameservers", {
|
|
"domain_identifier": "example.com",
|
|
"nameservers": [
|
|
"ns1.mycustomns.com",
|
|
"ns2.mycustomns.com"
|
|
]
|
|
})
|
|
|
|
# Revert to default nameservers
|
|
await mcp_client.call_tool("set_default_nameservers", {
|
|
"domain_identifier": "example.com"
|
|
})
|
|
```
|
|
|
|
### SSL Certificate Management
|
|
|
|
```python
|
|
# List all SSL certificates
|
|
await mcp_client.call_tool("list_ssl_certificates")
|
|
|
|
# Get certificate details (supports smart lookup)
|
|
await mcp_client.call_tool("get_ssl_info", {
|
|
"ssl_identifier": "example.com" # Can use hostname or certificate ID
|
|
})
|
|
```
|
|
|
|
### Account Information
|
|
|
|
```python
|
|
# Get account details
|
|
await mcp_client.call_tool("get_account_info")
|
|
|
|
# Check account balance
|
|
await mcp_client.call_tool("get_account_balance")
|
|
```
|
|
|
|
## 📋 Available Tools
|
|
|
|
### Domain Tools
|
|
| Tool | Description | Smart Identifiers |
|
|
|------|-------------|-------------------|
|
|
| `list_domains` | List all domains in account | ✓ |
|
|
| `get_domain_info` | Get detailed domain information | Domain name |
|
|
| `check_domain_availability` | Check if domains are available | ✓ |
|
|
| `register_domain` | Register a new domain | ✓ |
|
|
| `renew_domain` | Renew existing domain | Domain name |
|
|
|
|
### DNS Tools
|
|
| Tool | Description | Smart Identifiers |
|
|
|------|-------------|-------------------|
|
|
| `get_dns_records` | Get DNS records for domain | Domain name |
|
|
| `set_dns_records` | Set DNS records for domain | Domain name |
|
|
| `set_default_nameservers` | Use Name Cheap nameservers | Domain name |
|
|
| `set_custom_nameservers` | Set custom nameservers | Domain name |
|
|
|
|
### SSL Tools
|
|
| Tool | Description | Smart Identifiers |
|
|
|------|-------------|-------------------|
|
|
| `list_ssl_certificates` | List SSL certificates | ✓ |
|
|
| `get_ssl_info` | Get certificate information | Certificate ID, hostname |
|
|
|
|
### Account Tools
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `get_account_info` | Get account information |
|
|
| `get_account_balance` | Get account balance |
|
|
|
|
## 📚 Available Resources
|
|
|
|
| Resource URI | Description |
|
|
|--------------|-------------|
|
|
| `namecheap://domains` | List all domains with status |
|
|
| `namecheap://domain/{domain_name}` | Detailed domain information |
|
|
| `namecheap://dns/{domain_name}` | DNS records for domain |
|
|
| `namecheap://nameservers/{domain_name}` | Nameserver configuration |
|
|
| `namecheap://ssl` | SSL certificates overview |
|
|
| `namecheap://ssl/{certificate_id}` | Detailed certificate info |
|
|
| `namecheap://account` | Account information |
|
|
| `namecheap://balance` | Account balance details |
|
|
|
|
## 🖥️ Command Line Interface
|
|
|
|
The package includes a comprehensive CLI for direct operations:
|
|
|
|
```bash
|
|
# List domains
|
|
mcp-namecheap domains list
|
|
|
|
# Check domain availability
|
|
mcp-namecheap domains check example.com newsite.org
|
|
|
|
# Get domain information
|
|
mcp-namecheap domains info example.com
|
|
|
|
# Get DNS records
|
|
mcp-namecheap dns get example.com
|
|
|
|
# List SSL certificates
|
|
mcp-namecheap ssl list
|
|
|
|
# Get account information
|
|
mcp-namecheap account info
|
|
|
|
# Get account balance
|
|
mcp-namecheap account balance
|
|
|
|
# Output in JSON format
|
|
mcp-namecheap domains list --json
|
|
```
|
|
|
|
## 🧪 Testing
|
|
|
|
The project includes comprehensive testing with multiple test types:
|
|
|
|
```bash
|
|
# Run all tests
|
|
python run_tests.py
|
|
|
|
# Run specific test types
|
|
python run_tests.py --unit # Unit tests only
|
|
python run_tests.py --integration # Integration tests only
|
|
python run_tests.py --mcp # MCP functionality tests only
|
|
|
|
# Run with coverage
|
|
python run_tests.py --coverage
|
|
|
|
# Code quality checks
|
|
python run_tests.py --lint # Ruff linting and formatting
|
|
python run_tests.py --format # Black and isort formatting
|
|
python run_tests.py --typecheck # Type checking with mypy
|
|
python run_tests.py --all # Everything
|
|
|
|
# Auto-fix formatting and linting
|
|
python run_tests.py --format --fix
|
|
python run_tests.py --lint --fix
|
|
```
|
|
|
|
### Test Structure
|
|
- **Unit Tests**: Individual component testing with mocks
|
|
- **Integration Tests**: Component interaction testing
|
|
- **MCP Tests**: FastMCP in-memory testing for all tools
|
|
- **Coverage Goal**: 80%+ overall, 100% for critical MCP tools
|
|
|
|
## 🔧 Development
|
|
|
|
### Setup Development Environment
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone https://github.com/your-org/mcp-namecheap
|
|
cd mcp-namecheap
|
|
|
|
# Install with development dependencies
|
|
uv install -e ".[dev]"
|
|
|
|
# Install pre-commit hooks
|
|
pre-commit install
|
|
|
|
# Copy environment template
|
|
cp .env.example .env
|
|
# Edit .env with your credentials
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
# Format code with Ruff (fast)
|
|
ruff format src/ tests/
|
|
ruff check --fix src/ tests/
|
|
|
|
# Format code with Black and isort
|
|
black src/ tests/
|
|
isort src/ tests/
|
|
|
|
# Type check
|
|
mypy src/mcp_namecheap/
|
|
|
|
# Run all quality checks
|
|
python run_tests.py --all
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
mcp-namecheap/
|
|
├── src/mcp_namecheap/
|
|
│ ├── __init__.py # Package exports
|
|
│ ├── __main__.py # python -m entry point
|
|
│ ├── client.py # High-level client with smart identifiers
|
|
│ ├── server.py # Core API client with error handling
|
|
│ ├── fastmcp_server.py # FastMCP server implementation
|
|
│ ├── cli.py # Command-line interface
|
|
│ ├── domains.py # Domain management tools
|
|
│ ├── dns.py # DNS management tools
|
|
│ ├── ssl.py # SSL certificate tools
|
|
│ └── account.py # Account management tools
|
|
├── tests/
|
|
│ ├── conftest.py # Test fixtures
|
|
│ ├── test_mcp_server.py # MCP functionality tests
|
|
│ ├── test_client.py # Client tests
|
|
│ └── test_server.py # Core server tests
|
|
├── CLAUDE.md # Development documentation
|
|
├── README.md # This file
|
|
├── pyproject.toml # Project configuration
|
|
└── run_tests.py # Comprehensive test runner
|
|
```
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. **Fork the repository**
|
|
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
|
|
3. **Make changes with tests**: Ensure high test coverage
|
|
4. **Run quality checks**: `python run_tests.py --all`
|
|
5. **Commit changes**: `git commit -m 'Add amazing feature'`
|
|
6. **Push to branch**: `git push origin feature/amazing-feature`
|
|
7. **Create Pull Request**
|
|
|
|
### Contribution Guidelines
|
|
- Maintain 80%+ test coverage
|
|
- Follow type hints and documentation standards
|
|
- Ensure all quality checks pass
|
|
- Add tests for new features
|
|
- Update documentation as needed
|
|
|
|
## 📝 API Response Format
|
|
|
|
All MCP tools return a standardized response format:
|
|
|
|
```python
|
|
# Success response
|
|
{
|
|
"success": true,
|
|
"data": {...}, # API response data
|
|
"message": "Operation completed successfully"
|
|
}
|
|
|
|
# Error response
|
|
{
|
|
"success": false,
|
|
"error": "Error description",
|
|
"message": "Operation failed"
|
|
}
|
|
```
|
|
|
|
## 🚨 Error Handling
|
|
|
|
The server provides comprehensive error handling with specific exception types:
|
|
|
|
- **`NameCheapAPIError`**: Base exception for all API errors
|
|
- **`NameCheapAuthError`**: Authentication/authorization errors
|
|
- **`NameCheapNotFoundError`**: Resource not found errors
|
|
- **`NameCheapRateLimitError`**: Rate limit exceeded errors
|
|
- **`NameCheapValidationError`**: Input validation errors
|
|
|
|
## 🔒 Security
|
|
|
|
- **No Secrets in Code**: All API credentials via environment variables
|
|
- **Input Validation**: Comprehensive validation using Pydantic models
|
|
- **Rate Limiting**: Respect Name Cheap API rate limits
|
|
- **Timeout Configuration**: Proper HTTP timeouts (30s total, 10s connect)
|
|
- **Sandbox Support**: Safe testing environment
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## 🔗 Related Links
|
|
|
|
- [Name Cheap API Documentation](https://www.namecheap.com/support/api/intro/)
|
|
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
|
|
- [Model Context Protocol](https://modelcontextprotocol.io/)
|
|
- [Issue Tracker](https://github.com/your-org/mcp-namecheap/issues)
|
|
|
|
## 📞 Support
|
|
|
|
- **Documentation**: [GitHub README](https://github.com/your-org/mcp-namecheap#readme)
|
|
- **Issues**: [GitHub Issues](https://github.com/your-org/mcp-namecheap/issues)
|
|
- **Discussions**: [GitHub Discussions](https://github.com/your-org/mcp-namecheap/discussions)
|
|
|
|
---
|
|
|
|
**Built with ❤️ using FastMCP and the Model Context Protocol** |