# Namecheap MCP Server

An MCP server for managing DNS records and domains via the [Namecheap API](https://www.namecheap.com/support/api/methods/). Works with Claude.ai, Claude Desktop, Claude Code, and any MCP client.

## Tools

| Tool | Description |
|------|-------------|
| `setup` | Detects the server IP and walks you through enabling the Namecheap API |
| `list_domains` | List all domains in your account with status, expiry, auto-renew |
| `get_domain_info` | Detailed info for a domain: nameservers, whois, registration dates |
| `list_dns_records` | List all DNS records for a domain |
| `add_dns_record` | Add a DNS record (safely preserves existing records) |
| `update_dns_record` | Update a record matched by host + type |
| `delete_dns_record` | Delete a record matched by host + type |
| `set_nameservers` | Set custom nameservers or reset to Namecheap defaults |

## Quick Start (claude.ai)

1. Add `https://namecheap-mcp-production.up.railway.app/` as a remote MCP server in claude.ai
2. You'll be redirected to a login page — enter your Namecheap username and API key
3. On your first tool call, if the server IP isn't whitelisted, you'll get a message with the exact IP and a direct link to whitelist it
4. Whitelist the IP, and you're done — every future session auto-authenticates via OAuth

Your credentials are encrypted into the OAuth token (AES-256-GCM). Nothing is stored on the server.

### Namecheap API setup

If you don't have API access yet:

1. [Enable API access](https://ap.www.namecheap.com/settings/tools/apiaccess) in your Namecheap account
2. [Whitelist the server IP](https://ap.www.namecheap.com/settings/tools/apiaccess/whitelisted-ips) shown on the login page or in the first tool call error
3. Copy your API key from the API Access page

### IP changes

The server runs on Railway, whose outbound IP may occasionally change. If it does, your next tool call will tell you the new IP with a link to whitelist it. No need to re-authenticate — your OAuth token survives IP changes.

## Authentication

The server supports three auth methods (tried in order):

| Method | Best for | How it works |
|--------|----------|--------------|
| **OAuth** | claude.ai, any OAuth-capable client | Login page, credentials encrypted into token |
| **Authorization header** | Claude Code, programmatic use | `Authorization: Bearer user:key:ip` |
| **URL path** | Simple setup | `https://server/user/key/ip` |

## Self-Hosted Setup

### Install & run locally (stdio)

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

Add to Claude Desktop config:

```json
{
  "mcpServers": {
    "namecheap": {
      "command": "node",
      "args": ["/path/to/namecheap-mcp/dist/index.js"],
      "env": {
        "NAMECHEAP_API_USER": "your_username",
        "NAMECHEAP_API_KEY": "your_api_key",
        "NAMECHEAP_CLIENT_IP": "your_whitelisted_ip"
      }
    }
  }
}
```

### Run as HTTP server (with OAuth)

```bash
OAUTH_SECRET="$(openssl rand -hex 32)" \
BASE_URL="https://your-domain.com" \
node dist/index.js --http
```

## How it works

The Namecheap API's `setHosts` command **replaces all DNS records** on every call. This server handles that safely — when you add, update, or delete a single record, it fetches all existing records first, modifies the list, then writes everything back.

### Security

- **Stateless OAuth** — credentials are AES-256-GCM encrypted into the token. The server stores nothing.
- **PKCE supported** — authorization codes use S256 code challenge verification.
- **Auth codes expire** after 5 minutes.
- **IP errors are actionable** — if the server IP changes, tool calls return the new IP with a direct whitelist link.
- **Stdio mode** reads credentials from local env vars only.

## Environment Variables

| Variable | Mode | Required | Description |
|----------|------|----------|-------------|
| `NAMECHEAP_API_USER` | stdio | Yes | Your Namecheap username |
| `NAMECHEAP_API_KEY` | stdio | Yes | API key from Namecheap dashboard |
| `NAMECHEAP_CLIENT_IP` | stdio | Yes | Your whitelisted IP address |
| `OAUTH_SECRET` | HTTP | Yes | 32+ char secret for token encryption |
| `BASE_URL` | HTTP | Yes | Public URL of the server |
| `PORT` | HTTP | No | Server port (default 3000) |

## License

MIT