# @rezlazy/namesilo-mcp

MCP server for the [NameSilo Domain API](https://www.namesilo.com/api-reference). Published as [`@rezlazy/namesilo-mcp`](https://www.npmjs.com/package/@rezlazy/namesilo-mcp).

Exposes **67 tools** covering registration, transfers, DNS, contacts, nameservers, privacy, forwarding, email, portfolios, account funds, marketplace, and auctions.

All NameSilo operations are HTTPS GET. This server authenticates with your API key and returns JSON `reply` objects (success code `300`).

## Requirements

- Node.js 20+
- A NameSilo API key from [API Manager](https://www.namesilo.com/account_api.php)

Whitelist the IP that will call the API if your key is restricted.

## Cursor configuration

Add to `.cursor/mcp.json` or Cursor MCP settings:

```json
{
  "mcpServers": {
    "namesilo": {
      "command": "npx",
      "args": ["-y", "@rezlazy/namesilo-mcp"],
      "env": {
        "NAMESILO_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

From GitHub (builds `dist` via `prepare` on install):

```json
{
  "mcpServers": {
    "namesilo": {
      "command": "npx",
      "args": ["-y", "github:Rezlazy/namesilo-mcp"],
      "env": {
        "NAMESILO_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

The default branch includes `prepare`. Pin a later release with `github:Rezlazy/namesilo-mcp#v0.1.1` (v0.1.0 does not build from git).

For local development (`.cursor/mcp.json` in this repo):

```json
{
  "mcpServers": {
    "namesilo": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}
```

Create `.env` in the project root:

```env
NAMESILO_API_KEY=your_api_key
```

### Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `NAMESILO_API_KEY` | yes | API key from API Manager |
| `NAMESILO_SANDBOX` | no | `true` to use `https://sandbox.namesilo.com` (request sandbox credentials from NameSilo) |
| `NAMESILO_BATCH` | no | `true` to send **all** calls to `/apibatch`. Required for high-volume jobs; see [batch policy](https://www.namesilo.com/support/v2/articles/account-options/api-automated-batch) |
| `NAMESILO_API_URL` | no | Override the standard API base |
| `NAMESILO_BATCH_URL` | no | Override the batch API base |

`registerDomainDrop` always uses `/apibatch`, even when `NAMESILO_BATCH` is unset.

## Typical workflow

1. **`checkRegisterAvailability`** — see if a name can be registered
2. **`contactList`** / **`contactAdd`** — get a `contact_id`
3. **`registerDomain`** — spends account funds (or `payment_id`)
4. **`dnsListRecords`** then **`dnsAddRecord`** / **`dnsUpdateRecord`**
5. **`changeNameServers`** if the domain should not use NameSilo DNS

Money-moving tools: `registerDomain`, `registerDomainDrop`, `renewDomain`, `transferDomain`, `addAccountFunds`, `bidAuction`, `buyNowAuction`.

## Tools

### Domains

| Tool | Description |
|------|-------------|
| `checkRegisterAvailability` | Check if domains can be registered (max 200) |
| `registerDomain` | Register a domain |
| `registerDomainDrop` | Drop-catch a domain (`/apibatch`) |
| `renewDomain` | Renew a domain |
| `listDomains` | List domains in the account |
| `getDomainInfo` | Domain status, dates, lock, privacy, NS |
| `addAutoRenewal` / `removeAutoRenewal` | Auto-renew on/off |
| `domainLock` / `domainUnlock` | Transfer lock |
| `domainPush` | Push domains to another NameSilo account |
| `whoisInfo` | WHOIS lookup |
| `listExpiringDomains` / `countExpiringDomains` | Expiry window |
| `getPrices` | TLD price list |

### Transfers

| Tool | Description |
|------|-------------|
| `checkTransferAvailability` | Can these domains transfer in? |
| `transferDomain` | Start an inbound transfer |
| `checkTransferStatus` | Transfer status |
| `transferUpdateChangeEPPCode` | Set/change EPP code |
| `transferUpdateResendAdminEmail` | Re-send admin approval email |
| `transferUpdateResubmitToRegistry` | Re-submit to registry |
| `retrieveAuthCode` | Email the EPP code (transfer away) |

### Contacts

| Tool | Description |
|------|-------------|
| `contactList` | List or fetch contact profiles |
| `contactAdd` | Create a profile (`fn`, `ln`, `ad`, `cy`, `st`, `zp`, `ct`, `em`, `ph`) |
| `contactUpdate` | Update a profile |
| `contactDelete` | Delete an unused profile |
| `contactDomainAssociate` | Attach contacts to a domain |

### DNS & DNSSEC

| Tool | Description |
|------|-------------|
| `dnsListRecords` | List records |
| `dnsAddRecord` | Add A/AAAA/CNAME/MX/TXT/SRV/CAA/NS |
| `dnsUpdateRecord` | Update by `rrid` |
| `dnsDeleteRecord` | Delete by `rrid` |
| `dnsSecListRecords` | List DS records |
| `dnsSecAddRecord` / `dnsSecDeleteRecord` | Manage DS records |

### Nameservers

| Tool | Description |
|------|-------------|
| `changeNameServers` | Set ns1–ns13 (or `nameservers[]`) for up to 200 domains |
| `listRegisteredNameServers` | Glue hosts |
| `addRegisteredNameServer` | Add glue host |
| `modifyRegisteredNameServer` | Change glue host |
| `deleteRegisteredNameServer` | Delete glue host |

### Privacy, forwarding, email, portfolios

| Tool | Description |
|------|-------------|
| `addPrivacy` / `removePrivacy` | WHOIS privacy |
| `domainForward` | Forward a domain |
| `domainForwardSubDomain` | Forward a subdomain |
| `domainForwardSubDomainDelete` | Remove subdomain forward |
| `listEmailForwards` | List forwards |
| `configureEmailForward` | Add/change a forward |
| `deleteEmailForward` | Delete a forward |
| `registrantVerificationStatus` | ICANN email verification status |
| `emailVerification` | Send verification email |
| `portfolioList` / `portfolioAdd` / `portfolioDelete` | Portfolios |
| `portfolioDomainAssociate` | Assign domains to a portfolio |

### Account, marketplace, auctions

| Tool | Description |
|------|-------------|
| `getAccountBalance` | Account funds |
| `addAccountFunds` | Charge a saved card |
| `listOrders` / `orderDetails` | Order history |
| `marketplaceActiveSalesOverview` | Your marketplace listings |
| `marketplaceAddOrModifySale` | Create/update/cancel a sale |
| `marketplaceLandingPageUpdate` | For-sale landing page |
| `listAuctions` / `viewAuction` / `viewAuctions` | Expired-domain auctions |
| `viewAuctionHistory` / `watchAuction` | History and watchlist |
| `bidAuction` / `buyNowAuction` | Bid or buy-now |

## Development

```bash
npm install
cp .env.example .env   # set NAMESILO_API_KEY
npm test
npm run typecheck
npm run build
```

Contact field names follow the NameSilo API (`fn`, `ln`, `ad`, …). See the [API reference](https://www.namesilo.com/api-reference) for TLD-specific fields (`usnc`/`usap` for `.us`, CIRA fields for `.ca`).

## Publishing

GitHub Actions publishes to npm when a GitHub Release is created (`v0.1.0`, …). The repository needs an `NPM_TOKEN` secret (Automation token from [npmjs.com](https://www.npmjs.com/)).

To publish locally after `npm login`:

```bash
npm publish --access public
```

## Changelog

See [CHANGELOG.md](./CHANGELOG.md).

## License

MIT