MCP Name Cheap

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

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

   cp .env.example .env
   # Edit .env with your credentials
   

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

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

{
  "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

# 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

# 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

# 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

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

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

# 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

# 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

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

# 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 file for details.

🔗 Related Links

• Name Cheap API Documentation
• FastMCP Documentation
• Model Context Protocol
• Issue Tracker

📞 Support

• Documentation: GitHub README
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built with ❤️ using FastMCP and the Model Context Protocol