# @appouse/godaddy-dns-mcp

![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![Node](https://img.shields.io/badge/node-%E2%89%A518.17-brightgreen)
![MCP](https://img.shields.io/badge/MCP-compatible-green)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for managing **GoDaddy DNS records**. It lets Claude and other AI assistants list, add, replace and delete DNS records on any domain in your GoDaddy account — and check whether a domain is still available to register.

Written in TypeScript and published to npm, so it runs with a single `npx` command — nothing to clone, install or build.

## Table of Contents

- [Quick start](#quick-start)
- [Configuration](#configuration)
- [Tools](#tools)
- [Usage](#usage)
- [Programmatic use](#programmatic-use)
- [Security](#security)
- [Development](#development)
- [License](#license)

## Quick start

Requires **Node.js 18.17 or newer**.

```bash
npx -y @appouse/godaddy-dns-mcp --help
```

There is nothing to clone or build — `npx` fetches the package on demand. To install it permanently:

```bash
npm install -g @appouse/godaddy-dns-mcp
godaddy-dns-mcp --version
```

## Configuration

### 1. Get GoDaddy API credentials

Generate a **Production** API key at [developer.godaddy.com/keys](https://developer.godaddy.com/keys) — select *Production*, not OTE. OTE keys point at GoDaddy's test environment and will not see your real domains.

The API returns `ACCESS_DENIED` for keys on accounts with fewer than 10 domains or without an eligible plan; that is a GoDaddy account restriction, not a problem with this server.

### 2. Register the server with your MCP client

**Claude Code** — `claude mcp add`, or add this to the `mcpServers` section of `~/.claude.json`:

```json
"godaddy-dns": {
  "command": "npx",
  "args": ["-y", "@appouse/godaddy-dns-mcp"],
  "env": {
    "GODADDY_API_KEY": "your_api_key",
    "GODADDY_API_SECRET": "your_api_secret"
  }
}
```

**Claude Desktop** — same block, in `claude_desktop_config.json`:

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

```json
{
  "mcpServers": {
    "godaddy-dns": {
      "command": "npx",
      "args": ["-y", "@appouse/godaddy-dns-mcp"],
      "env": {
        "GODADDY_API_KEY": "your_api_key",
        "GODADDY_API_SECRET": "your_api_secret"
      }
    }
  }
}
```

Restart the client to pick up the change.

### 3. Any other MCP client

The server speaks MCP over **stdio**. Run it directly:

```bash
GODADDY_API_KEY=your_key GODADDY_API_SECRET=your_secret npx -y @appouse/godaddy-dns-mcp
```

### Environment variables

| Variable | Required | Description |
|---|---|---|
| `GODADDY_API_KEY` | yes | Production API key |
| `GODADDY_API_SECRET` | yes | Matching API secret |

Credentials are read at request time, so the server starts even when they are missing — it logs a warning to stderr and every tool call reports the problem instead of failing silently.

## Tools

| Tool | Description |
|---|---|
| `list_dns_records` | List all records for a domain, optionally filtered by type and/or name |
| `add_dns_record` | Add a record without overwriting existing ones of the same type (`PATCH`) |
| `replace_dns_records` | Overwrite **all** records of a given type + name — use when exactly one record should exist (`PUT`). Supports `dry_run` |
| `delete_dns_record` | Delete **all** records matching a given type and name. Supports `dry_run` |
| `check_domain_availability` | Check whether a domain is available to register, with price and currency |

**Supported record types:** A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, and anything else the GoDaddy API accepts.

### Parameters

| Parameter | Tools | Default | Notes |
|---|---|---|---|
| `domain` | all | — | Root domain, e.g. `example.com` |
| `record_type` | all except availability | — | Case-insensitive; sent upper-cased |
| `name` | all except availability | — | Subdomain; `@` for the apex, `*` for a wildcard |
| `data` | add, replace | — | Record value (IP, hostname, text …) |
| `ttl` | add, replace | `3600` | Seconds |
| `priority` | add, replace | `0` | Only sent for `MX` and `SRV` |
| `dry_run` | replace, delete | `false` | Preview only — makes no API call |
| `check_type` | availability | `FAST` | `FAST` (cached) or `FULL` (authoritative) |

> **Safety:** the two destructive tools accept `dry_run`. With `dry_run=true` they describe exactly what *would* change and make **no** call to the GoDaddy API — useful for confirming a change before committing to it.

`list_dns_records` and `check_domain_availability` also return [structured content](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content), so clients that support it get typed results instead of a JSON blob in text.

## Usage

Once registered, ask your assistant in plain language:

> "Add a CNAME record for `app.example.com` pointing to `cname.vercel-dns.com`"

> "List all A records for `example.com`"

> "Show me what deleting the TXT record `_vercel` from `example.com` would do, but don't do it yet"

> "Is `myneatidea.dev` still available?"

## Programmatic use

The package also ships as a library if you want to embed the tools in your own MCP server or script:

```ts
import { createServer, GoDaddyClient, listDnsRecords } from "@appouse/godaddy-dns-mcp";

// A ready-to-connect MCP server
const server = createServer();

// Or just the API layer
const client = new GoDaddyClient({ apiKey: "…", apiSecret: "…" });
const records = await listDnsRecords(client, { domain: "example.com", record_type: "A" });
```

## Security

- **Credentials never leave your machine.** They are read from the environment and sent only to `api.godaddy.com` over HTTPS, and are never included in tool output or error messages.
- **Inputs are validated before a URL is built.** `domain`, `record_type` and `name` all end up in the request path, so each is checked against a DNS-shaped pattern; slashes, query strings, percent escapes and `..` traversal are rejected before any request is made.
- **Requests time out** after 30 seconds instead of hanging a client session.
- **`replace_dns_records` and `delete_dns_record` are destructive** — they affect *every* record matching the type and name. Prefer `dry_run=true` first, and remember that most MCP clients let you require approval per tool.
- **Never commit API credentials.** Put them in your MCP client config or a local `.env` that is git-ignored.

## Development

```bash
git clone https://github.com/appouse/godaddy-dns-mcp
cd godaddy-dns-mcp
npm install

npm run typecheck   # tsc --noEmit
npm test            # vitest — all HTTP traffic is stubbed
npm run build       # emit dist/
npm run dev         # run from source with tsx
```

Tests cover the API layer, the input validation, the MCP protocol surface (via an in-memory transport) and the built CLI as a real subprocess over stdio. No test ever contacts GoDaddy.

Inspect the server interactively:

```bash
npm run build
npx @modelcontextprotocol/inspector node dist/cli.js
```

## License

MIT — see [LICENSE](LICENSE).