@ironclads/namecheap-mcp/README.md

MCP server for Namecheap API integration - domain management, DNS, and domain suggestions

# Namecheap MCP Server

[![npm version](https://badge.fury.io/js/%40ironclads%2Fnamecheap-mcp.svg)](https://badge.fury.io/js/%40ironclads%2Fnamecheap-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides programmatic access to Namecheap domain management services. This server enables AI assistants like Claude to interact with Namecheap's API for domain operations, DNS management, and domain suggestions.

## Features

- 🔍 **Domain Availability Checking**: Single and bulk domain availability checks
- 📋 **Domain Management**: List, register, and renew domains in your account
- 🌐 **DNS Management**: Get and set nameservers for your domains
- 💡 **Domain Suggestions**: AI-powered domain name suggestions with availability checking
- 🔐 **Secure Authentication**: Environment variable support for API credentials
- 🧪 **Sandbox Support**: Safe testing with Namecheap's sandbox environment

## Installation

### Global Installation (Recommended)

```bash
npm install -g @ironclads/namecheap-mcp@1.4.4
```

### Verify Installation

```bash
namecheap-mcp --help
```

## Configuration

### API Credentials

1. **Get Namecheap API credentials**:
   - Visit [Namecheap API Settings](https://ap.www.namecheap.com/settings/tools/apiaccess/)
   - Enable API access and note your API key
   - Whitelist your IP address

2. **Set environment variables**:
   ```bash
   export NAMECHEAP_API_USER=your-api-user
   export NAMECHEAP_API_KEY=your-api-key
   export NAMECHEAP_USERNAME=your-username
   export NAMECHEAP_CLIENT_IP=your-whitelisted-ip
   export NAMECHEAP_SANDBOX=true  # Set to 'false' for production
   ```

### Usage Methods

#### Method 1: Environment Variables Only
```bash
# Set environment variables (as shown above)
namecheap-mcp
```

#### Method 2: CLI Arguments
```bash
namecheap-mcp \
  --api-user your-api-user \
  --api-key your-api-key \
  --username your-username \
  --client-ip your-whitelisted-ip \
  --sandbox
```

#### Method 3: Mixed (CLI overrides environment)
```bash
export NAMECHEAP_API_USER=your-api-user
namecheap-mcp --api-key your-api-key --username your-username --client-ip your-ip
```

## Claude Desktop Integration

### Configuration File Location

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

### Configuration Example

```json
{
  "mcpServers": {
    "namecheap": {
      "command": "namecheap-mcp",
      "args": [],
      "env": {
        "NAMECHEAP_API_USER": "your-api-user",
        "NAMECHEAP_API_KEY": "your-api-key",
        "NAMECHEAP_USERNAME": "your-username", 
        "NAMECHEAP_CLIENT_IP": "your-whitelisted-ip",
        "NAMECHEAP_SANDBOX": "true"
      }
    }
  }
}
```

### Reload Configuration

After updating the configuration file:

```bash
# In Claude Desktop
/mcp reload
```

## Available MCP Tools

### Domain Management

| Tool | Description |
|------|-------------|
| `check_domain` | Check if a single domain is available |
| `check_domains_bulk` | Check availability of multiple domains (up to 50) |
| `list_domains` | List all domains in your Namecheap account |
| `get_domain_info` | Get detailed information about a registered domain |
| `register_domain` | Register a new domain |
| `renew_domain` | Renew an existing domain registration |

### DNS Management

| Tool | Description |
|------|-------------|
| `get_nameservers` | Get current nameservers for a domain |
| `set_nameservers` | Set custom nameservers for a domain |

### Domain Suggestions

| Tool | Description |
|------|-------------|
| `suggest_domains` | Generate intelligent domain suggestions with availability checking |

## Usage Examples

### Check Domain Availability

```json
{
  "tool": "check_domain",
  "arguments": {
    "domain": "example.com"
  }
}
```

### List Your Domains

```json
{
  "tool": "list_domains",
  "arguments": {
    "page": 1,
    "pageSize": 20,
    "sortBy": "EXPIREDATE"
  }
}
```

### Get Domain Suggestions

```json
{
  "tool": "suggest_domains", 
  "arguments": {
    "keyword": "tech",
    "tlds": ["com", "io", "co", "ai"],
    "maxSuggestions": 10,
    "includeHyphens": false,
    "maxLength": 12
  }
}
```

### Set Nameservers

```json
{
  "tool": "set_nameservers",
  "arguments": {
    "domain": "example.com", 
    "nameservers": [
      "ns1.cloudflare.com",
      "ns2.cloudflare.com"
    ]
  }
}
```

## Domain Suggestion Features

The domain suggestion system includes:

- **Smart Generation**: Uses prefixes, suffixes, and alternative words
- **Availability Checking**: Real-time availability verification
- **Scoring System**: Rates suggestions based on length, pronounceability, and brandability
- **Multiple TLDs**: Supports checking across different top-level domains
- **Flexible Options**: Configurable parameters for hyphens, numbers, and length limits

## Troubleshooting

### Common Issues

1. **"Command not found" Error**
   ```bash
   # Make sure the package is installed globally
   npm install -g @ironclads/namecheap-mcp@1.4.4
   
   # Check installation
   which namecheap-mcp
   ```

2. **API Authentication Errors**
   - Verify your API credentials at [Namecheap API Settings](https://ap.www.namecheap.com/settings/tools/apiaccess/)
   - Ensure your IP address is whitelisted
   - Check that API access is enabled for your account

3. **MCP Connection Issues**
   - Verify Claude Desktop configuration file location
   - Check JSON syntax in configuration file
   - Try `/mcp reload` in Claude Desktop
   - Check environment variables are set correctly

4. **Sandbox vs Production**
   - Use `NAMECHEAP_SANDBOX=true` for testing
   - Set `NAMECHEAP_SANDBOX=false` for production operations
   - Sandbox and production have separate API endpoints

### Debug Mode

Enable debug logging:

```bash
DEBUG=* namecheap-mcp
```

### Getting Help

```bash
namecheap-mcp --help
```

## Development

### Building from Source

```bash
git clone https://github.com/your-repo/namecheap-mcp.git
cd namecheap-mcp
npm install
npm run build
```

### Running Tests

```bash
npm test
```

### Type Checking

```bash
npm run typecheck
```

## API Reference

For detailed information about Namecheap's API, visit:
- [Namecheap API Documentation](https://www.namecheap.com/support/api/intro/)
- [API Methods Reference](https://www.namecheap.com/support/api/methods/)

## Security

- **Environment Variables**: Store API credentials in environment variables, not in code
- **IP Whitelisting**: Only whitelisted IP addresses can use the API
- **Sandbox Mode**: Always test in sandbox mode before production use
- **Key Rotation**: Regularly rotate your API keys

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Changelog

### v1.4.4 (Latest)
- ✅ Added comprehensive README.md and updated documentation
- ✅ Improved Claude Desktop integration examples  
- ✅ Enhanced troubleshooting and installation guides
- ✅ Added security considerations and API limitations

### v1.4.3
- ✅ Fixed npx execution issues with proper bin permissions
- ✅ Added comprehensive environment variable support
- ✅ Improved error handling and validation
- ✅ Added `list_domains` tool for account domain management

### v1.4.2
- ✅ Added environment variable support alongside CLI arguments
- ✅ Enhanced security with environment-based configuration
- ✅ Updated documentation and help messages

### v1.4.1
- ✅ Added domain list functionality
- ✅ Removed dotenv dependencies for simpler configuration
- ✅ Improved domain validation and scoring algorithms

## Support

- 📧 **Issues**: [GitHub Issues](https://github.com/your-repo/namecheap-mcp/issues)
- 📖 **Documentation**: [Namecheap API Docs](https://www.namecheap.com/support/api/intro/)
- 💬 **Community**: [Model Context Protocol](https://modelcontextprotocol.io/)

---

Made with ❤️ for the MCP ecosystem