{"_id":"@aiwerk/mcp-server-hetzner","_rev":"2-59e1e896f7db4d717a7344fb13e964b8","name":"@aiwerk/mcp-server-hetzner","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@aiwerk/mcp-server-hetzner","version":"0.1.0","keywords":["mcp","hetzner","cloud","model-context-protocol"],"author":{"name":"AIWerk","email":"kontakt@aiwerk.ch"},"license":"MIT","_id":"@aiwerk/mcp-server-hetzner@0.1.0","maintainers":[{"name":"agbergsmann","email":"kontakt@aiwerk.ch"}],"homepage":"https://aiwerkmcp.com/#/catalog/hetzner","bugs":{"url":"https://github.com/AIWerk/mcp-server-hetzner/issues"},"bin":{"mcp-server-hetzner":"dist/src/server.js"},"dist":{"shasum":"c8c09f7fa7027ec0dc7d07b61805c7cce8f5c8d5","tarball":"https://registry.npmjs.org/@aiwerk/mcp-server-hetzner/-/mcp-server-hetzner-0.1.0.tgz","fileCount":9,"integrity":"sha512-zRkGvq9wdZexiY4DhYUV1PPZuUx+DIKTIE3Gl2omgAmq6nTZlIFE+PeQCc6/tJ+qMVPB3kcJ+7ptuprWK6dxHw==","signatures":[{"sig":"MEUCIQDjw+9HH2gdVPRGJXn8sMzJE6BK/EgNq2itJr0qOlPQLwIgKJnGDCsjitWwpPOsFJGnir4P4yKX0n5DaDEbsld5c40=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":191453},"main":"dist/src/server.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"61693b4f96e0e0e194cf07fdf42c2a0ddca57aa3","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc -p tsconfig.json","start":"node dist/src/server.js","predev":"npm run gen-version","pretest":"npm run gen-version && bash -c 'pkill -9 -f \"[n]ode.*vitest\" 2>/dev/null; pkill -9 -f \"[e]sbuild.*--service\" 2>/dev/null; true'","generate":"node scripts/generate-tools.mjs","posttest":"bash -c 'pkill -9 -f \"[n]ode.*vitest\" 2>/dev/null; pkill -9 -f \"[e]sbuild.*--service\" 2>/dev/null; true'","prebuild":"npm run gen-version","gen-version":"node scripts/gen-version.mjs","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"agbergsmann","email":"kontakt@aiwerk.ch"},"repository":{"url":"git+https://github.com/AIWerk/mcp-server-hetzner.git","type":"git"},"_npmVersion":"10.9.4","description":"Hetzner Cloud API MCP server — full vendor surface (189 tools, BYOK, DRY_RUN + READ_ONLY)","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.19.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.1","typescript":"^5.5.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-hetzner_0.1.0_1778533930111_0.028037100905150325","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aiwerk/mcp-server-hetzner","version":"0.1.1","description":"Hetzner Cloud API MCP server — full vendor surface (189 tools, BYOK, DRY_RUN + READ_ONLY)","type":"module","main":"dist/src/server.js","bin":{"mcp-server-hetzner":"dist/src/server.js"},"scripts":{"gen-version":"node scripts/gen-version.mjs","prebuild":"npm run gen-version","build":"tsc -p tsconfig.json","start":"node dist/src/server.js","predev":"npm run gen-version","dev":"tsc --watch","pretest":"npm run gen-version && bash -c 'pkill -9 -f \"[n]ode.*vitest\" 2>/dev/null; pkill -9 -f \"[e]sbuild.*--service\" 2>/dev/null; true'","test":"vitest run","posttest":"bash -c 'pkill -9 -f \"[n]ode.*vitest\" 2>/dev/null; pkill -9 -f \"[e]sbuild.*--service\" 2>/dev/null; true'","generate":"node scripts/generate-tools.mjs","prepublishOnly":"npm run build && npm test"},"engines":{"node":">=18.0.0"},"keywords":["mcp","hetzner","cloud","model-context-protocol"],"author":{"name":"AIWerk","email":"kontakt@aiwerk.ch"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/AIWerk/mcp-server-hetzner.git"},"homepage":"https://aiwerkmcp.com/#/catalog/hetzner","bugs":{"url":"https://github.com/AIWerk/mcp-server-hetzner/issues"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.19.1","zod":"^3.25.76"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.5.0","vitest":"^3.2.1"},"_id":"@aiwerk/mcp-server-hetzner@0.1.1","gitHead":"c1d0c9dbf57a427ce619ff3e6eed07b599a8a036","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-q8kA1DJG6kk9H5/ZsotzE0wAKxHsiCUorTRsDZJpyab5xyMJ29n4mP4jYb99GXCGpTfV39Iyn6mphiavlkZbrw==","shasum":"6231b262e45e209cd69f6ffdec8137ff566f1f97","tarball":"https://registry.npmjs.org/@aiwerk/mcp-server-hetzner/-/mcp-server-hetzner-0.1.1.tgz","fileCount":9,"unpackedSize":197484,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCZ8cTCyF8N0KR7Ial9BBaNl7vT0rDKexiaUL2ZPG7r6QIgEW/DOpvF0I0CWSVAVpuWKr63IKTqiO3AD5SSQlLo6t0="}]},"_npmUser":{"name":"agbergsmann","email":"kontakt@aiwerk.ch"},"directories":{},"maintainers":[{"name":"agbergsmann","email":"kontakt@aiwerk.ch"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-hetzner_0.1.1_1778535753784_0.14601382734570723"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-11T21:12:10.044Z","modified":"2026-05-11T21:42:34.082Z","0.1.0":"2026-05-11T21:12:10.326Z","0.1.1":"2026-05-11T21:42:33.948Z"},"bugs":{"url":"https://github.com/AIWerk/mcp-server-hetzner/issues"},"author":{"name":"AIWerk","email":"kontakt@aiwerk.ch"},"license":"MIT","homepage":"https://aiwerkmcp.com/#/catalog/hetzner","keywords":["mcp","hetzner","cloud","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/AIWerk/mcp-server-hetzner.git"},"description":"Hetzner Cloud API MCP server — full vendor surface (189 tools, BYOK, DRY_RUN + READ_ONLY)","maintainers":[{"name":"agbergsmann","email":"kontakt@aiwerk.ch"}],"readme":"# @aiwerk/mcp-server-hetzner\n\nFull-surface Hetzner Cloud MCP server — 189 tools covering the entire Hetzner Cloud + DNS API. BYOK, DRY_RUN and READ_ONLY safety layers.\n\n## Install\n\n```bash\nnpx -y @aiwerk/mcp-server-hetzner\n```\n\n## Configure\n\nAdd to your MCP client config (e.g. Claude Desktop `config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"hetzner\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aiwerk/mcp-server-hetzner\"],\n      \"env\": {\n        \"HCLOUD_TOKEN\": \"<your-api-token>\"\n      }\n    }\n  }\n}\n```\n\n### Environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `HCLOUD_TOKEN` | **Yes** | — | Hetzner Cloud API token (Bearer). Create at Hetzner Console → Project → Security → API Tokens. |\n| `HETZNER_API_TIMEOUT_MS` | No | `30000` | Request timeout in milliseconds. |\n| `DRY_RUN` | No | `0` | Set to `1` to intercept all write operations without touching the API. Logs the would-be request to stderr. Useful for agent debugging. |\n| `READ_ONLY` | No | `0` | Set to `1` to refuse all write operations entirely. Takes precedence over `DRY_RUN`. Useful for ops safety. |\n\n## Auth\n\nCreate an API token at [Hetzner Console](https://console.hetzner.cloud/) → Your Project → Security → API Tokens.\n\n- **Read-only token**: safe for listing resources, no billing risk.\n- **Read-write token**: required for creating/modifying/deleting resources. Note that writes to Servers, Volumes, Load Balancers, Floating IPs, and Primary IPs incur Hetzner billing.\n\n## Safety layers\n\nTwo independent safety layers protect against accidental writes:\n\n| Mode | Behavior on writes |\n|---|---|\n| `DRY_RUN=1` | Logs the would-be request to stderr, returns `{ dry_run: true, would_send: { method, path, body, query } }`. Read operations pass through normally. |\n| `READ_ONLY=1` | Refuses all write operations with a clear error. Takes precedence over DRY_RUN. Read operations pass through normally. |\n\nWhen both are set, `READ_ONLY` wins.\n\n## What we guarantee (testable)\n\nThese promises are backed by tests that fail if the safety code is removed.\n\n- **`DRY_RUN=1` blocks all write network calls.** Test: [`tests/safety/dry-run-no-network.test.ts`](tests/safety/dry-run-no-network.test.ts)\n- **`READ_ONLY=1` refuses all write tools and never touches the network.** Test: [`tests/safety/read-only-no-network.test.ts`](tests/safety/read-only-no-network.test.ts)\n- **`READ_ONLY` takes precedence over `DRY_RUN` when both are set.** Test: [`tests/safety/read-only-wins.test.ts`](tests/safety/read-only-wins.test.ts)\n- **`DRY_RUN=1` does not block GET (read) operations.** Test: [`tests/safety/dry-run-get-passthrough.test.ts`](tests/safety/dry-run-get-passthrough.test.ts)\n- **`READ_ONLY=1` does not block GET (read) operations.** Test: [`tests/safety/read-only-get-passthrough.test.ts`](tests/safety/read-only-get-passthrough.test.ts)\n- **`HCLOUD_TOKEN` is scrubbed from all error messages and error bodies.** Test: [`tests/safety/token-redaction.test.ts`](tests/safety/token-redaction.test.ts)\n- **No auto-retry on 401, 403, 5xx in v0.1.0.** Test: [`tests/safety/no-retry-on-auth-fail.test.ts`](tests/safety/no-retry-on-auth-fail.test.ts)\n\n## Tools (189)\n\nTools cover the full vendor surface across 31 tag groups:\n\n| Tag group | Count |\n|---|---|\n| Server Actions | 27 |\n| Load Balancer Actions | 17 |\n| Network Actions | 10 |\n| Floating IP Actions | 8 |\n| Primary IP Actions | 8 |\n| Volume Actions | 8 |\n| Zone Actions | 8 |\n| Firewall Actions | 7 |\n| Load Balancers | 6 |\n| Servers | 6 |\n| Zones | 6 |\n| Zone RRSet Actions | 6 |\n| Certificates | 5 |\n| Certificate Actions | 5 |\n| Firewalls | 5 |\n| Floating IPs | 5 |\n| Image Actions | 5 |\n| Networks | 5 |\n| Placement Groups | 5 |\n| Primary IPs | 5 |\n| SSH Keys | 5 |\n| Volumes | 5 |\n| Zone RRSets | 5 |\n| Images | 4 |\n| Actions | 2 |\n| Data Centers | 2 |\n| ISOs | 2 |\n| Load Balancer Types | 2 |\n| Locations | 2 |\n| Server Types | 2 |\n| Pricing | 1 |\n\n### Key tools\n\n| Tool | Description |\n|---|---|\n| `list_servers` | List all servers (paginated). |\n| `get_server` | Get a single server by ID. |\n| `create_server` | Create a new server. Billing starts immediately. |\n| `delete_server` | Delete a server. Irreversible. |\n| `poweron_server` / `poweroff_server` | Power operations. |\n| `create_server_image` | Create a snapshot of a server. |\n| `list_locations` | List available locations (cheapest read-only call, safe for smoke tests). |\n| `list_volumes` | List block volumes. |\n| `list_load_balancers` | List load balancers. |\n| `list_firewalls` | List firewalls. |\n| `set_firewall_rules` | **Replaces ALL existing rules.** Read current state first via `get_firewall`. |\n| `list_zones` | List DNS zones. |\n| `list_zone_rrsets` | List DNS record sets in a zone. |\n\n### Pagination\n\nAll `list_*` tools accept `page` (default 1) and `per_page` (default 25, max 50). Check `meta.pagination.last_page` and `meta.pagination.total_entries` in the response to determine if more pages exist.\n\n### Plural vs singular action tools\n\nHetzner distinguishes per-resource and project-wide action endpoints by pluralizing the resource noun:\n\n- `list_server_actions(server_id)` — actions for ONE specific server\n- `list_servers_actions()` — all server actions across the project\n\nSame pattern applies to: certificates, firewalls, floating_ips, images, load_balancers, networks, primary_ips, volumes, zones.\n\n## Development\n\n```bash\n# Install\nnpm install\n\n# Generate tools from OpenAPI spec\nnpm run generate\n\n# Build\nnpm run build\n\n# Test (all 243 tests including 13 safety-claim tests)\nnpm test\n\n# Smoke test\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | HCLOUD_TOKEN=<token> node dist/src/server.js\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"create_server\",\"arguments\":{\"name\":\"test\",\"server_type\":\"cx22\",\"image\":\"ubuntu-24.04\",\"location\":\"fsn1\"}}}' | HCLOUD_TOKEN=<token> DRY_RUN=1 node dist/src/server.js\n```\n\n## License\n\nMIT — [AIWerk](https://aiwerkmcp.com)\n","readmeFilename":"README.md"}