Skip to main content
Glama
README.md
# mcp-regru-mtls

MCP server for managing DNS records via the [Reg.ru API 2.0](https://www.reg.ru/reseller/api2doc), with **client TLS certificate (mTLS) support**.

A fork of [konser80/mcp-regru](https://github.com/konser80/mcp-regru). The upstream server authenticates with a username and password only. Some Reg.ru accounts additionally require a client certificate ("SSL для API"), and such accounts answer every password-only request with:

```json
{ "result": "error", "error_code": "NO_CERTIFICATE", "error_text": "..." }
```

This fork keeps everything upstream does and adds certificate authentication, so the same MCP server works for both kinds of accounts.

Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), [OpenCode](https://opencode.ai) and any other MCP-compatible client.

## Requirements

- Node.js >= 18
- A [Reg.ru](https://www.reg.ru/) account with API 2.0 access enabled

## Installation

```bash
git clone https://github.com/FerrumLogic/mcp-regru-mtls.git
cd mcp-regru-mtls
npm install
npm run build
```

The server entry point is `dist/index.js` (absolute path needed in client configs).

## Configuration

All settings come from environment variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `REGRU_USERNAME` | Yes | Reg.ru account username |
| `REGRU_PASSWORD` | Yes | Reg.ru account password |
| `REGRU_CERT_PATH` | No | Path to the client certificate (PEM), e.g. `/home/me/.creds/regru.crt` |
| `REGRU_KEY_PATH` | No | Path to the certificate private key (PEM), e.g. `/home/me/.creds/regru.key` |
| `REGRU_CERT_BASE64` | No | The same certificate, base64-encoded, in a single variable |
| `REGRU_KEY_BASE64` | No | The same private key, base64-encoded, in a single variable |
| `REGRU_PROXY` | No | HTTP proxy URL (e.g. `http://user:pass@host:port`) |

Certificate settings are resolved in this order:

1. **Files** — `REGRU_CERT_PATH` + `REGRU_KEY_PATH`
2. **Base64** — `REGRU_CERT_BASE64` + `REGRU_KEY_BASE64` (fallback, convenient for Docker, CI and remote agents)
3. **Nothing set** — password-only authentication, exactly like upstream

Only one of the two pairs is used: if the path pair is complete, the base64 pair is ignored. A *half-specified* pair (`cert` without `key`, or the reverse) is a startup error — the server prints the problem to stderr and exits with code 1 instead of silently dropping mTLS and failing later with a confusing `NO_CERTIFICATE`.

At startup the server logs which mode it picked (to stderr, so it never pollutes the stdio MCP channel):

```
Using client certificate: files /home/me/.creds/regru.crt / /home/me/.creds/regru.key
Using client certificate: base64 environment variables
No client certificate configured, using password-only authentication
```

## mTLS: client certificates

### Why it is needed

Reg.ru can protect API 2.0 with a client certificate. When that option is on, the API validates the TLS client certificate **in addition to** username and password. Without a certificate the connection is rejected with `NO_CERTIFICATE`, no matter how correct the password is. This is mutual TLS (mTLS): both sides present a certificate.

The upstream server only sends `username`/`password` in the POST body, so it cannot work with such an account. This fork loads the certificate and private key into the TLS layer via [undici](https://github.com/nodejs/undici)'s `Agent`, so the handshake itself carries the certificate.

### How to get a certificate in the Reg.ru panel

1. Generate a self-signed key pair (Reg.ru accepts a self-signed certificate; the public part is uploaded to the panel):

   ```bash
   openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
     -keyout regru.key -out regru.crt \
     -subj "/CN=regru-api-client"
   chmod 600 regru.key
   ```

2. In the Reg.ru personal account open **Настройки безопасности** → <https://www.reg.ru/user/prefs/security> and click **«Управление сертификатами»**. Follow the instructions there and upload the contents of `regru.crt`.

3. Keep `regru.key` private: it is the secret half of the pair. Store both files outside the repository, for example in `~/.creds/regru/`, and never commit them.

4. Make sure the machine's public IP is allowed in the API settings as well — Reg.ru checks the IP allowlist independently of the certificate (see [Troubleshooting](#troubleshooting)).

### Mode 1 — certificate files (recommended for a workstation)

```json
{
  "REGRU_USERNAME": "your_username",
  "REGRU_PASSWORD": "your_password",
  "REGRU_CERT_PATH": "/home/you/.creds/regru/regru.crt",
  "REGRU_KEY_PATH": "/home/you/.creds/regru/regru.key"
}
```

Paths are read once at startup. The key may be an unencrypted PEM (`BEGIN PRIVATE KEY` or `BEGIN RSA PRIVATE KEY`); encrypted keys are not supported by Node's TLS stack without a passphrase, so generate the pair with `-nodes`.

### Mode 2 — base64 in environment variables (Docker, CI, remote agents)

Useful when there is no filesystem to mount, or when secrets are injected as environment values by a secret manager:

```bash
# one-line base64, no wrapping
base64 -w0 regru.crt   # Linux
base64 regru.crt | tr -d '\n'   # macOS
```

Then set:

```json
{
  "REGRU_USERNAME": "your_username",
  "REGRU_PASSWORD": "your_password",
  "REGRU_CERT_BASE64": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
  "REGRU_KEY_BASE64": "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t..."
}
```

Whitespace inside the value is ignored, and literal `\n` sequences are tolerated, so a PEM pasted with escaped newlines still decodes.

> Base64 is an encoding, not encryption. Anyone who can read the environment of the process can read the key — protect the config file with `chmod 600` and prefer a secret manager where available.

### Mode 3 — password only (upstream behaviour)

If the account does not require a certificate, set neither pair and the server behaves exactly like upstream:

```json
{
  "REGRU_USERNAME": "your_username",
  "REGRU_PASSWORD": "your_password"
}
```

### Certificates and proxy together

If both `REGRU_PROXY` and a certificate pair are set, the certificate is attached to the proxy tunnel's TLS handshake (`requestTls` of undici's `ProxyAgent`), so mTLS keeps working through an HTTP proxy instead of being silently dropped.

## Client configuration

### Claude Code

Project-level `.mcp.json` in the repository root, or `~/.claude/settings.json` for all projects:

```json
{
  "mcpServers": {
    "regru": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-regru-mtls/dist/index.js"],
      "env": {
        "REGRU_USERNAME": "your_username",
        "REGRU_PASSWORD": "your_password",
        "REGRU_CERT_PATH": "/home/you/.creds/regru/regru.crt",
        "REGRU_KEY_PATH": "/home/you/.creds/regru/regru.key"
      }
    }
  }
}
```

Same with base64 instead of paths — swap the two `*_PATH` keys for `REGRU_CERT_BASE64` / `REGRU_KEY_BASE64`.

### Cursor

`.cursor/mcp.json` in the project or `~/.cursor/mcp.json` globally:

```json
{
  "mcpServers": {
    "regru": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-regru-mtls/dist/index.js"],
      "env": {
        "REGRU_USERNAME": "your_username",
        "REGRU_PASSWORD": "your_password",
        "REGRU_CERT_PATH": "/home/you/.creds/regru/regru.crt",
        "REGRU_KEY_PATH": "/home/you/.creds/regru/regru.key"
      }
    }
  }
}
```

### OpenCode

`opencode.json` (project) or `~/.config/opencode/opencode.json` (global). Note that OpenCode uses `command` as an array and `environment` instead of `env`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "regru": {
      "type": "local",
      "command": ["node", "/absolute/path/to/mcp-regru-mtls/dist/index.js"],
      "environment": {
        "REGRU_USERNAME": "your_username",
        "REGRU_PASSWORD": "your_password",
        "REGRU_CERT_PATH": "/home/you/.creds/regru/regru.crt",
        "REGRU_KEY_PATH": "/home/you/.creds/regru/regru.key"
      }
    }
  }
}
```

For base64 in OpenCode, keep the values on a single line inside `environment`:

```json
"environment": {
  "REGRU_USERNAME": "your_username",
  "REGRU_PASSWORD": "your_password",
  "REGRU_CERT_BASE64": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
  "REGRU_KEY_BASE64": "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t..."
}
```

### Other MCP clients

Use the stdio transport your client supports: command `node`, argument `/absolute/path/to/mcp-regru-mtls/dist/index.js`, and the environment variables listed above.

## Tools

| Tool | Description |
|------|-------------|
| `regru_check_domain_availability` | Check if one or more domains are available for registration |
| `regru_get_dns_records` | Get all DNS records for a domain |
| `regru_add_a_record` | Add an A record (IPv4) |
| `regru_add_aaaa_record` | Add an AAAA record (IPv6) |
| `regru_add_cname_record` | Add a CNAME record (alias) |
| `regru_add_mx_record` | Add an MX record (mail exchange) |
| `regru_add_txt_record` | Add a TXT record (SPF, DKIM, verification) |
| `regru_add_ns_record` | Add an NS record (nameserver delegation) |
| `regru_add_srv_record` | Add an SRV record (service discovery) |
| `regru_add_caa_record` | Add a CAA record (certificate authority) |
| `regru_remove_record` | Remove a specific DNS record |
| `regru_update_records` | Bulk add/remove DNS records |
| `regru_update_soa` | Update SOA record TTL settings |
| `regru_update_nss` | Replace the domain's authoritative nameservers (with optional glue records) |
| `regru_get_nss` | Get the domain's current authoritative nameservers |
| `regru_clear_zone` | Remove all DNS records (destructive) |

## Usage examples

Once configured, manage DNS through natural language:

- "Is example.com available?"
- "Check example.com, example.ru and example.net"
- "Show DNS records for example.com"
- "Point www.example.com to 1.2.3.4"
- "Add an MX record for Google Workspace"
- "Add an SPF record for example.com"
- "Remove the old A record for api.example.com"

## Troubleshooting

| Symptom | Cause and fix |
|---------|----------------|
| `NO_CERTIFICATE` in the API response | The account requires a client certificate and none was sent. Set `REGRU_CERT_PATH`+`REGRU_KEY_PATH` or the base64 pair. |
| `ERROR: REGRU_CERT_PATH and REGRU_KEY_PATH must be set together` | Only half of the pair is configured. Set both variables or neither. |
| `ERROR: Cannot read REGRU_CERT_PATH (...): file not found` | Wrong path, or the client runs as a different user. Use an absolute path and check `chmod`/ownership. |
| `ERROR: Cannot read ... : permission denied` | The key is not readable by the user running the MCP client. `chmod 600` the key and make sure the owner is correct. |
| `ACCESS_DENIED_FROM_IP` | Reg.ru rejects the request because the machine's public IP is not in the API allowlist. Add the IP in the personal account; the certificate does not replace the allowlist. |
| TLS handshake errors mentioning the key | The key does not match the certificate, or it is passphrase-protected. Regenerate the pair with `openssl req -x509 -nodes ...`. |
| Server starts but tools fail with auth errors | Check `REGRU_USERNAME`/`REGRU_PASSWORD`; the certificate is an extra factor, not a replacement. |

Server diagnostics go to stderr and appear in the MCP client's log for this server.

## Security notes

- Never commit `*.crt`, `*.key`, `*.pem`, `.env` files or base64-encoded keys. `.gitignore` in this repository already covers the common certificate extensions.
- Keep the private key outside the repository (`~/.creds/...`) and readable only by your user (`chmod 600`).
- Base64 variables are convenient but not secret storage: config files holding them need `chmod 600`.
- Rotate the pair if the key may have leaked: upload the new certificate in the Reg.ru panel and replace both files/variables.

## Development

```bash
npm run dev    # Watch mode with tsx
npm run build  # Compile TypeScript
npm start      # Run compiled server
```

`ARCHITECTURE.md` describes the code layout and how to add a new tool.

## License

MIT — see [LICENSE](LICENSE).

Original project: [konser80/mcp-regru](https://github.com/konser80/mcp-regru), © konser80.
mTLS support and base64 configuration: © FerrumLogic.