Metadata-Version: 2.5
Name: barie-hetzner-mcp
Version: 0.1.0
Summary: Hetzner Cloud and Storage Box MCP server for DevOps agents
Author-email: Barie <support@barie.ai>
License: MIT
Keywords: devops,hetzner,hetzner-cloud,mcp,model-context-protocol,storage-box
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2.0.0,>=1.2.0
Description-Content-Type: text/markdown

# Barie Hetzner MCP Server

An MCP server that lets an AI agent inspect and operate Hetzner infrastructure through the
[Hetzner Cloud API](https://docs.hetzner.cloud/reference/cloud) and the
[Hetzner API](https://docs.hetzner.cloud/reference/hetzner) (Storage Boxes). It is built for
DevOps use, with safety rules enforced by the server rather than left to the agent.

## Safety model

Every tool belongs to one of three tiers. The tiers you have not enabled are hidden from the
agent, and calling them by name is refused.

| Tier | Enabled | Examples |
|---|---|---|
| **read** | Always | inventory, server metrics, DNS records, certificates, recent actions |
| **write** | Unless `--read-only` | reboot, snapshot, DNS upsert, firewall rules, attach volume, LB targets |
| **dangerous** | Only with `--allow-dangerous`, and every call needs `confirm=true` | create/delete/rebuild/resize server, delete resources, hard power-off, storage box rollback |

Further protections:

- Hetzner **delete/rebuild protection** is respected. The server never turns it off.
- **Secrets are stripped** from results. `create_server` requires SSH keys, so no root password is
  generated, and any `root_password` the API returns is redacted.
- **Async operations are awaited**: tools return the final status, not "started".
- `firewall_set_rules`, `upsert_dns_record` and `update_labels` return the **previous state**, so
  changes can be reverted.
- Every change, including refused calls, is written as one **JSON audit line** to stderr, and
  optionally to `--audit-log`.
- Logs go to stderr only. stdout is the MCP protocol channel.

For a hard guarantee, use a **Read**-type API token together with `--read-only`. The API then
rejects writes even if the server had a bug.

## Installation

Requirements:
- Python 3.10+
- A Hetzner Console project API token: Project → Security → API Tokens

```bash
pip install -e .
barie-hetzner-mcp --api-token <TOKEN> --read-only
```

## Configuration

```json
{
  "mcpServers": {
    "barie-hetzner-mcp": {
      "command": "uvx",
      "args": ["barie-hetzner-mcp", "--api-token", "YOUR_HETZNER_API_TOKEN", "--read-only"]
    }
  }
}
```

| Option | Default | Description |
|---|---|---|
| `--api-token` | `$HETZNER_API_TOKEN` | Project API token, used for both APIs |
| `--read-only` | off | Expose and allow read tools only |
| `--allow-dangerous` | off | Expose the dangerous tier (ignored with `--read-only`) |
| `--action-timeout` | `120` | Seconds to wait for async operations before returning `running` |
| `--audit-log` | none | Also append the audit log to this file |

A token belongs to one Hetzner project. To work with another project, start the server with
that project's token.

## Tools

**Read (20)**
- **Overview:** `project_overview`
- **Servers:** `list_servers`, `get_server`, `get_server_metrics`, `list_server_types`, `list_images`, `list_ssh_keys`
- **Storage and networking:** `list_volumes`, `list_firewalls`, `list_networks`, `list_ips`, `list_load_balancers`, `list_certificates`
- **DNS:** `list_dns_zones`, `list_dns_records`
- **Storage Boxes:** `list_storage_boxes`, `get_storage_box`, `list_storage_box_snapshots`
- **Actions:** `list_recent_actions`, `get_action`

**Write (13)**
- **Servers:** `server_power` (poweron / shutdown / reboot), `create_server_snapshot`, `set_server_backups`
- **Labels and DNS:** `update_labels`, `upsert_dns_record`
- **Firewalls:** `firewall_set_rules`, `firewall_resources`
- **Volumes, IPs and load balancers:** `volume_attachment`, `resize_volume`, `ip_assignment`, `lb_target`
- **Storage Boxes:** `storage_box_snapshot`, `storage_box_snapshot_plan`

**Dangerous (6)**
- **Servers:** `create_server`, `rebuild_server`, `change_server_type`
- **Deletion and rollback:** `delete_resource`, `delete_dns_record`, `rollback_storage_box_snapshot`
- Also `server_power` with `poweroff` or `reset`

Resources can be referenced by ID or by exact name. Results are compact JSON summaries,
not raw API objects.

## License

MIT
