REG.RU Zone Manager MCP Server

A Model Context Protocol (MCP) server for managing DNS zones through the REG.RU API 2.0. This server provides tools for inspecting zones and for adding, replacing, and deleting DNS records.

Features

• Zone Management: List zones, inspect records, and clear a zone
• Record Management: Add, replace, and delete DNS records (A, AAAA, CNAME, MX, TXT, NS, SRV)
• REG.RU API 2.0: Uses the documented zone/* endpoints
• Error Handling: REG.RU API, per-domain, and network errors surfaced to the client
• Type Safety: Written in TypeScript; tool arguments are described by JSON Schema

Prerequisites

• Node.js 18+ (npx ships with npm)
• REG.RU account with API access
• REG.RU API credentials (username and password)

Setup

There is nothing to install or build. MCP clients launch the server on demand with npx, which fetches the package on first use and caches it afterwards.

You only need REG.RU API credentials:

1. Log in to your REG.RU account
2. Navigate to API settings
3. Generate API credentials
4. Add your machine's outbound IP to the API IP whitelist — REG.RU rejects unlisted addresses, which is the most common cause of authentication failures

Adding the server to an MCP client

The server speaks MCP over stdio. A client launches it as a subprocess and passes credentials through the environment; you do not start it yourself.

Claude Code

claude mcp add reg-ru-zone-manager \
  -e REG_RU_USERNAME=your_username \
  -e REG_RU_PASSWORD=your_password \
  -- npx -y reg-ru-mcp-server

Add -s user to make the server available in every project, or -s project to share it with your team via .mcp.json. The default scope is local (this project only).

Verify it connected:

claude mcp list

Claude Desktop

Add the server to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "reg-ru-zone-manager": {
      "command": "npx",
      "args": ["-y", "reg-ru-mcp-server"],
      "env": {
        "REG_RU_USERNAME": "your_username",
        "REG_RU_PASSWORD": "your_password"
      }
    }
  }
}

Restart Claude Desktop for the change to take effect.

Other MCP clients

Any stdio-capable MCP client works with the same three pieces. A ready-to-adapt copy of this block ships as mcp-config.json in the repository:

| Field | Value | |-------|-------| | Transport | stdio | | Command | npx | | Arguments | -y reg-ru-mcp-server | | Environment | REG_RU_USERNAME, REG_RU_PASSWORD |

Deferred tool loading

Tool definitions consume context in every request. If you run many MCP servers, you can have this server's tools loaded on demand rather than upfront. This is a client-side setting — the server does not declare it — configured per server in .claude.json:

{
  "mcpServers": {
    "reg-ru-zone-manager": {
      "command": "npx",
      "args": ["-y", "reg-ru-mcp-server"],
      "defer_loading": true
    }
  }
}

The client then loads these tools only when they are searched for. Support varies by client and it may require tool search to be enabled.

Pinning a version

npx -y reg-ru-mcp-server resolves to the latest published version. To pin, name it explicitly:

npx -y [email protected]

Running from a clone

To run a local checkout instead of the published package — when developing, or to use an unreleased change — build it and point the client at the compiled entry point using an absolute path:

npm install
npm run build

{
  "mcpServers": {
    "reg-ru-zone-manager": {
      "command": "node",
      "args": ["/absolute/path/to/reg-ru-mcp/dist/index.js"],
      "env": {
        "REG_RU_USERNAME": "your_username",
        "REG_RU_PASSWORD": "your_password"
      }
    }
  }
}

Environment variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | REG_RU_USERNAME | Your REG.RU username | Yes | - | | REG_RU_PASSWORD | Your REG.RU password | Yes | - | | REG_RU_API_URL | REG.RU API base URL | No | https://api.reg.ru/api/regru2/ |

The server exits immediately with an error on stderr if REG_RU_USERNAME or REG_RU_PASSWORD is missing, which a client surfaces as a failed connection.

Pass credentials through the MCP client configuration. A .env file is also read, but only when the server runs with the repository as its working directory, so it applies to a clone rather than to an npx launch.

Verifying the connection

Once registered, ask your client to list the account's zones. That calls list_zones, the only read-only tool that touches the account, and confirms credentials, IP whitelisting, and transport in one step:

"List my REG.RU DNS zones"

Available Tools

Note on record identity: REG.RU has no per-record IDs. A record is identified by the combination of subdomain, type, and content. Tools that modify records take those fields rather than an ID.

Zone Management

list_zones

List all DNS zones for your REG.RU account.

Parameters: None

Example:

{
  "name": "list_zones",
  "arguments": {}
}

get_zone

Get DNS zone information and all records for a specific domain.

Parameters:

• domain_name (string, required): The domain name to get zone information for

Example:

{
  "name": "get_zone",
  "arguments": {
    "domain_name": "example.com"
  }
}

clear_zone

Delete all resource records in a zone. Destructive and not reversible.

Parameters:

• domain_name (string, required): The domain name of the zone to clear

Example:

{
  "name": "clear_zone",
  "arguments": {
    "domain_name": "example.com"
  }
}

REG.RU API 2.0 has no zone create or delete operation — a zone exists implicitly for every domain in the account. clear_zone (zone/clear) is the closest equivalent to deleting one.

Record Management

add_record

Add a DNS record to a zone. Each record type is routed to its own REG.RU endpoint (zone/add_alias, zone/add_mx, zone/add_txt, and so on).

Parameters:

• domain_name (string, required): The domain name of the zone
• record_type (string, required): A, AAAA, CNAME, MX, TXT, NS, or SRV
• content (string, required): IP for A/AAAA, target hostname for CNAME/MX/NS/SRV, text for TXT
• subdomain (string, optional): The subdomain (defaults to @ for root domain)
• priority (number, optional): MX (default 10) and SRV (default 0)
• service (string, SRV only, required): Service and protocol, e.g. _sip._tcp
• weight (number, SRV only, optional): Relative weight (default 0)
• port (number, SRV only, required): Target port

Example:

{
  "name": "add_record",
  "arguments": {
    "domain_name": "example.com",
    "record_type": "A",
    "content": "192.168.1.1",
    "subdomain": "www"
  }
}

update_record

Replace an existing DNS record. The old record is removed and the new one added in a single atomic zone/update_records call.

Parameters:

• domain_name (string, required): The domain name of the zone
• old_record_type (string, required): Type of the record to replace
• old_subdomain (string, optional): Subdomain of the record to replace (defaults to @)
• old_content (string, optional): Current value. Omit to replace every record of that type on the subdomain
• plus all add_record parameters describing the replacement record

Example:

{
  "name": "update_record",
  "arguments": {
    "domain_name": "example.com",
    "old_record_type": "A",
    "old_subdomain": "www",
    "old_content": "192.168.1.1",
    "record_type": "A",
    "subdomain": "www",
    "content": "192.168.1.2"
  }
}

delete_record

Delete DNS records from a zone, identified by subdomain and type.

Parameters:

• domain_name (string, required): The domain name of the zone
• record_type (string, required): The type of DNS record to delete
• subdomain (string, optional): The subdomain (defaults to @)
• content (string, optional): Only delete records with this exact value. Omit to delete every record of that type on the subdomain

Example:

{
  "name": "delete_record",
  "arguments": {
    "domain_name": "example.com",
    "subdomain": "www",
    "record_type": "A",
    "content": "192.168.1.1"
  }
}

DNS Record Types

| Type | Description | Example Content | Endpoint | |------|-------------|-----------------|----------| | A | IPv4 address | 192.168.1.1 | zone/add_alias | | AAAA | IPv6 address | 2001:db8::1 | zone/add_aaaa | | CNAME | Canonical name | www.example.com | zone/add_cname | | MX | Mail exchange | mail.example.com (with priority) | zone/add_mx | | TXT | Text record | v=spf1 include:_spf.google.com ~all | zone/add_txt | | NS | Name server | ns1.example.com | zone/add_ns | | SRV | Service record | sipserver.example.com (with service/port/weight) | zone/add_srv |

TTL is a zone-level setting in REG.RU (zone/update_soa), not a per-record one, so the record tools do not take a ttl parameter. get_zone reports the zone TTL.

Error Handling

Tool failures are returned to the client as an MCP tool result with isError: true and a human-readable message, rather than as a protocol error, so the model can read and react to them:

• API errors: REG.RU error codes and text are surfaced verbatim
• Per-domain errors: REG.RU returns a top-level success even when the individual domain failed, so per-domain results are checked and raised
• Network errors: Timeouts and connectivity failures are reported as Network error

Diagnostic logging goes to stderr, never stdout — stdout carries the MCP JSON-RPC stream and any stray write there corrupts the protocol. Most clients capture the server's stderr in their own logs; in Claude Code, use claude mcp list to see connection status and /mcp to inspect the server.

Security Considerations

• Pass credentials through your MCP client configuration rather than committing them
• Use IP whitelisting in your REG.RU account
• Prefer a dedicated API user account over your primary login
• clear_zone deletes every record in a zone and is not reversible

API Rate Limits

REG.RU applies the following limits:

• 1200 requests per hour per client
• 1200 requests per hour per IP address

The server does not throttle or retry on its own; a rate-limit rejection surfaces as a REG.RU API error.

Troubleshooting

The server does not appear in the client

• Confirm npx -y reg-ru-mcp-server runs on its own. It should print REG.RU Zone Manager MCP server running on stdio and then wait — that is correct behaviour, since it is listening for JSON-RPC on stdin. Press Ctrl+C to exit.
• The first launch downloads the package, which can exceed a client's startup timeout. Run the command once by hand to warm the npx cache, then reconnect.
• On a machine with no registry access, use the clone-based configuration above instead.
• Check the client's MCP logs for the server's stderr output.

The server runs an old version after an upgrade

npx caches the resolved package. Clear it, or pin the version explicitly:

npx -y reg-ru-mcp-server@latest

"REG_RU_USERNAME and REG_RU_PASSWORD environment variables are required"

The credentials did not reach the server process. Set them in the client configuration (-e for claude mcp add, or the env block in claude_desktop_config.json) rather than relying on your shell environment.

Authentication or access errors from REG.RU

1. Verify the username and password
2. Confirm your outbound IP is whitelisted in the REG.RU API settings
3. Confirm the domain exists in the account and is using REG.RU DNS servers

Contributing

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

When working on the server itself, npm run dev runs it from TypeScript via tsx and npm run watch reloads on change. Both are for development only — an MCP client should always be pointed at the built dist/index.js. Note that the server communicates over stdin/stdout, so running it directly in a terminal just waits for JSON-RPC input; drive it from a client or a test harness instead.

License

MIT License - see LICENSE file for details.

Support

For issues related to:

• This MCP server: Create an issue in this repository
• REG.RU API: Contact REG.RU support
• MCP protocol: Check the MCP documentation