@silentfuture/inwx-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SilentFuture UG (haftungsbeschraenkt)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @silentfuture/inwx-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for the [INWX](https://www.inwx.com) domain registrar.
+It lets Claude Code, Claude Desktop, Cursor and any other MCP client manage domains through
+INWX's official DomRobot JSON-RPC API: list and inspect domains, check availability and prices,
+start transfers, change nameservers, manage contact handles and INWX-hosted DNS zones.
+
+Built by [SilentFuture](https://silentfuture.de) while moving ~100 domains from legacy hosters
+to INWX and Cloudflare DNS. Uses the official `domrobot-client` package, no scraping.
+
+## Quick start
+
+Add to your MCP client configuration (Claude Code: `.mcp.json` in the project, or `claude mcp add`):
+
+```json
+{
+  "mcpServers": {
+    "inwx": {
+      "command": "npx",
+      "args": ["-y", "@silentfuture/inwx-mcp"],
+      "env": {
+        "INWX_USERNAME": "your-inwx-login",
+        "INWX_PASSWORD": "your-inwx-password",
+        "INWX_SHARED_SECRET": "",
+        "INWX_ENV": "live"
+      }
+    }
+  }
+}
+```
+
+| Variable | Meaning |
+|---|---|
+| `INWX_USERNAME` | INWX login (required) |
+| `INWX_PASSWORD` | INWX password (required) |
+| `INWX_SHARED_SECRET` | TOTP shared secret if two-factor auth is enabled on the account (optional) |
+| `INWX_ENV` | `live` (default) or `ote` for the INWX test system. OTE uses a separate account from [ote.inwx.com](https://ote.inwx.com) |
+
+Start with `INWX_ENV=ote` if you want to try the write tools without spending money.
+
+## Tools
+
+| Tool | Kind | DomRobot method |
+|---|---|---|
+| `account_info` | read | `account.info` |
+| `domain_list` | read | `domain.list` (filter, paging) |
+| `domain_info` | read | `domain.info` (contacts, nameservers, lock, renewal mode) |
+| `domain_check` | read | `domain.check` (up to 50 domains) |
+| `domain_price` | read | `domain.getPrices` |
+| `domain_log` | read | `domain.log` |
+| `domain_transfer` | write, costs money | `domain.transfer` (auth code, nameservers, contact handles) |
+| `domain_update` | write | `domain.update` (nameservers, transfer lock, renewal mode, contacts) |
+| `domain_renew` | write, costs money | `domain.renew` |
+| `contact_list`, `contact_info` | read | `contact.list`, `contact.info` |
+| `contact_create` | write | `contact.create` |
+| `nameserver_list`, `nameserver_info` | read | `nameserver.list`, `nameserver.info` |
+| `api_call` | expert | any DomRobot method with raw params |
+
+Every write tool accepts `testing: true`, which makes INWX validate the request without executing it.
+Tool descriptions state clearly when a call costs money, so an agent can ask before acting.
+
+## Example prompts
+
+- "List all .de domains in my INWX account with their expiry dates."
+- "Check whether example.com and example.io are available and what they cost per year."
+- "Transfer example.org to INWX with auth code XYZ, set the nameservers to bingo.ns.cloudflare.com and langston.ns.cloudflare.com, use contact 12345 for all roles. Dry run first."
+- "Switch the nameservers of all my domains that still point at ns1.oldhoster.example to Cloudflare."
+
+## Behaviour and safety
+
+- Logs in lazily on the first call and re-authenticates once if the INWX session expired (codes 2200/2201).
+- Response codes 1000-1999 are success; anything else is returned as an MCP tool error with INWX's code, message and reason.
+- Credentials are read from the environment only. Nothing is written to disk.
+- Transfers of gTLDs add one year of runtime; .de and .eu transfers keep their runtime. .de domains need an owner with a German address or a German admin contact.
+
+## Development
+
+```sh
+pnpm install
+pnpm dev          # runs src/index.ts via tsx
+pnpm build        # emits dist/index.js
+```
+
+Requirements: Node 22+, pnpm 10.
+
+## License
+
+MIT, SilentFuture UG (haftungsbeschraenkt). Not affiliated with INWX GmbH.

package/dist/index.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// inwx-mcp - MCP server for the INWX DomRobot JSON-RPC API.
+//
+// Environment:
+//   INWX_USERNAME       INWX login (required)
+//   INWX_PASSWORD       INWX password (required)
+//   INWX_SHARED_SECRET  TOTP shared secret, only if 2FA is enabled on the account
+//   INWX_ENV            "live" (default) or "ote" (test system, separate account at ote.inwx.com)
+//
+// Every tool talks to the API of the environment above. In "live" mode, transfers,
+// registrations and renewals cost real money. Read tools are safe; write tools are
+// named with a verb (transfer, update, renew, create, delete) and say so in their description.
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { ApiClient, Language } from "domrobot-client";
+import * as z from "zod/v4";
+const ENV = (process.env.INWX_ENV ?? "live").toLowerCase();
+const USERNAME = process.env.INWX_USERNAME ?? "";
+const PASSWORD = process.env.INWX_PASSWORD ?? "";
+const SHARED_SECRET = process.env.INWX_SHARED_SECRET ?? "";
+if (!USERNAME || !PASSWORD) {
+    console.error("inwx-mcp: INWX_USERNAME and INWX_PASSWORD must be set");
+    process.exit(1);
+}
+const apiUrl = ENV === "ote" ? ApiClient.API_URL_OTE : ApiClient.API_URL_LIVE;
+const client = new ApiClient(apiUrl, Language.EN, false);
+let loggedIn = false;
+async function login() {
+    const r = (await client.login(USERNAME, PASSWORD, SHARED_SECRET || undefined));
+    if (r.code !== 1000)
+        throw new Error(`INWX login failed: ${r.code} ${r.msg ?? ""}`);
+    loggedIn = true;
+}
+// Calls the API, logging in lazily and re-logging once if the session expired (code 2200/2201).
+async function call(method, params = {}) {
+    if (!loggedIn)
+        await login();
+    let r = (await client.callApi(method, params));
+    if (r.code === 2200 || r.code === 2201) {
+        loggedIn = false;
+        await login();
+        r = (await client.callApi(method, params));
+    }
+    if (r.code < 1000 || r.code >= 2000) {
+        const detail = [r.msg, r.reasonCode, r.reason].filter(Boolean).join(" | ");
+        throw new Error(`INWX ${method} failed: ${r.code} ${detail}`);
+    }
+    return (r.resData ?? {});
+}
+const text = (v) => ({ content: [{ type: "text", text: typeof v === "string" ? v : JSON.stringify(v, null, 2) }] });
+const fail = (e) => ({ isError: true, content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }] });
+const run = async (fn) => { try {
+    return text(await fn());
+}
+catch (e) {
+    return fail(e);
+} };
+const nsSchema = z.array(z.string().min(3)).min(2).max(8).describe("Nameserver hostnames, at least two");
+serveStdio(() => {
+    const server = new McpServer({ name: "inwx", version: "0.1.0" });
+    // ---------- account ----------
+    server.registerTool("account_info", {
+        description: `Account details and prepaid balance of the INWX account (${ENV}). Read-only.`,
+        inputSchema: z.object({}),
+    }, async () => run(() => call("account.info")));
+    // ---------- domains ----------
+    server.registerTool("domain_list", {
+        description: "List domains in the account with status, nameservers, renewal mode and expiry. Read-only. Filter by substring or TLD.",
+        inputSchema: z.object({
+            domain: z.string().optional().describe("Substring / wildcard filter, e.g. '*.de'"),
+            page: z.number().int().min(1).default(1),
+            pagelimit: z.number().int().min(1).max(500).default(200),
+        }),
+    }, async ({ domain, page, pagelimit }) => run(() => call("domain.list", { ...(domain ? { domain } : {}), page, pagelimit })));
+    server.registerTool("domain_info", {
+        description: "Full details of one domain in the account: status, contacts, nameservers, transfer lock, renewal mode, auth code where the registry exposes it. Read-only.",
+        inputSchema: z.object({ domain: z.string() }),
+    }, async ({ domain }) => run(() => call("domain.info", { domain, wide: 2 })));
+    server.registerTool("domain_check", {
+        description: "Availability check for one or more domains (registered elsewhere, free, or transferable). Read-only.",
+        inputSchema: z.object({ domains: z.array(z.string()).min(1).max(50) }),
+    }, async ({ domains }) => run(() => call("domain.check", { domain: domains })));
+    server.registerTool("domain_price", {
+        description: "Price list for TLDs (registration, renewal, transfer) in the account currency. Read-only.",
+        inputSchema: z.object({ tlds: z.array(z.string()).optional().describe("e.g. ['de','com'], empty = all") }),
+    }, async ({ tlds }) => run(() => call("domain.getPrices", tlds?.length ? { tld: tlds } : {})));
+    server.registerTool("domain_transfer", {
+        description: "WRITE, COSTS MONEY: start an inbound transfer of a domain to INWX. Needs the auth code from the current registrar, four contact handle ids (may be identical) and the nameservers to set. gTLDs add one year of runtime, .de/.eu keep theirs.",
+        inputSchema: z.object({
+            domain: z.string(),
+            authCode: z.string().min(1),
+            ns: nsSchema,
+            registrant: z.number().int().describe("Contact handle id for the owner"),
+            admin: z.number().int().optional().describe("Defaults to registrant"),
+            tech: z.number().int().optional().describe("Defaults to registrant"),
+            billing: z.number().int().optional().describe("Defaults to registrant"),
+            renewalMode: z.enum(["AUTORENEW", "AUTOEXPIRE", "AUTODELETE"]).default("AUTORENEW"),
+            testing: z.boolean().default(false).describe("true = validate only, do not execute"),
+        }),
+    }, async (p) => run(() => call("domain.transfer", {
+        domain: p.domain, authCode: p.authCode, ns: p.ns,
+        registrant: p.registrant, admin: p.admin ?? p.registrant, tech: p.tech ?? p.registrant, billing: p.billing ?? p.registrant,
+        renewalMode: p.renewalMode, testing: p.testing,
+    })));
+    server.registerTool("domain_update", {
+        description: "WRITE: change nameservers, transfer lock, renewal mode or contacts of a domain already at INWX. Only the given fields change.",
+        inputSchema: z.object({
+            domain: z.string(),
+            ns: nsSchema.optional(),
+            transferLock: z.boolean().optional(),
+            renewalMode: z.enum(["AUTORENEW", "AUTOEXPIRE", "AUTODELETE"]).optional(),
+            registrant: z.number().int().optional(),
+            admin: z.number().int().optional(),
+            tech: z.number().int().optional(),
+            billing: z.number().int().optional(),
+            testing: z.boolean().default(false),
+        }),
+    }, async (p) => run(() => {
+        const params = { domain: p.domain, testing: p.testing };
+        for (const k of ["ns", "renewalMode", "registrant", "admin", "tech", "billing"])
+            if (p[k] !== undefined)
+                params[k] = p[k];
+        if (p.transferLock !== undefined)
+            params.transferLock = p.transferLock ? 1 : 0;
+        return call("domain.update", params);
+    }));
+    server.registerTool("domain_renew", {
+        description: "WRITE, COSTS MONEY: renew a domain at INWX by N years.",
+        inputSchema: z.object({ domain: z.string(), period: z.string().default("1Y").describe("e.g. '1Y'"), testing: z.boolean().default(false) }),
+    }, async ({ domain, period, testing }) => run(async () => {
+        const info = await call("domain.info", { domain });
+        return call("domain.renew", { domain, period, expiration: info.exDate, testing });
+    }));
+    server.registerTool("domain_log", {
+        description: "Recent log entries for a domain (transfers, updates, registry messages). Read-only.",
+        inputSchema: z.object({ domain: z.string(), pagelimit: z.number().int().min(1).max(200).default(50) }),
+    }, async ({ domain, pagelimit }) => run(() => call("domain.log", { domain, pagelimit })));
+    // ---------- contacts ----------
+    server.registerTool("contact_list", {
+        description: "List contact handles (owner/admin/tech/billing) in the account. Read-only.",
+        inputSchema: z.object({}),
+    }, async () => run(() => call("contact.list", { pagelimit: 200 })));
+    server.registerTool("contact_info", {
+        description: "Details of one contact handle. Read-only.",
+        inputSchema: z.object({ id: z.number().int() }),
+    }, async ({ id }) => run(() => call("contact.info", { id, wide: 1 })));
+    server.registerTool("contact_create", {
+        description: "WRITE: create a contact handle (ORG or PERSON). For .de the owner needs a German address or a German admin contact.",
+        inputSchema: z.object({
+            type: z.enum(["ORG", "PERSON", "ROLE"]),
+            name: z.string(),
+            org: z.string().optional(),
+            street: z.string(),
+            city: z.string(),
+            pc: z.string().describe("Postal code"),
+            cc: z.string().length(2).describe("Country code, e.g. DE"),
+            voice: z.string().describe("+49.20212345678"),
+            email: z.string().email(),
+            testing: z.boolean().default(false),
+        }),
+    }, async (p) => run(() => call("contact.create", p)));
+    // ---------- nameserver zones (only if DNS is hosted at INWX) ----------
+    server.registerTool("nameserver_list", {
+        description: "List DNS zones hosted on INWX nameservers. Read-only. Not needed for domains whose DNS lives at Cloudflare.",
+        inputSchema: z.object({ domain: z.string().optional() }),
+    }, async ({ domain }) => run(() => call("nameserver.list", { ...(domain ? { domain } : {}), pagelimit: 200 })));
+    server.registerTool("nameserver_info", {
+        description: "Records of one INWX-hosted DNS zone. Read-only.",
+        inputSchema: z.object({ domain: z.string() }),
+    }, async ({ domain }) => run(() => call("nameserver.info", { domain })));
+    // ---------- escape hatch ----------
+    server.registerTool("api_call", {
+        description: "Expert tool: call any DomRobot method by name with raw params (see https://www.inwx.de/en/help/apidoc). WRITE methods execute for real in live mode; prefer the named tools.",
+        inputSchema: z.object({ method: z.string().regex(/^[a-z]+\.[A-Za-z]+$/), params: z.record(z.string(), z.unknown()).default({}) }),
+    }, async ({ method, params }) => run(() => call(method, params)));
+    return server;
+});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@silentfuture/inwx-mcp",
+  "version": "0.1.1",
+  "description": "MCP server for the INWX domain registrar: list, check, transfer and update domains, nameservers, contacts and DNS via the official DomRobot JSON-RPC API",
+  "type": "module",
+  "bin": {
+    "inwx-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "SilentFuture UG (haftungsbeschraenkt) <info@silentfuture.de> (https://silentfuture.de)",
+  "homepage": "https://github.com/SilentFuture/inwx-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SilentFuture/inwx-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SilentFuture/inwx-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "inwx",
+    "domrobot",
+    "domain",
+    "registrar",
+    "dns",
+    "nameserver",
+    "transfer",
+    "claude",
+    "ai-agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "domrobot-client": "3.3.0",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.8.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js"
+  }
+}