# hetrixmcp

A [Model Context Protocol](https://modelcontextprotocol.io) server for the [HetrixTools](https://hetrixtools.com) API v3, built with [FastMCP](https://gofastmcp.com).

## Requirements

- Python 3.14+
- [uv](https://docs.astral.sh/uv/) for package management
- A HetrixTools API token

## Setup

```bash
# Install dependencies
uv sync

# Set your HetrixTools API token
export HETRIXTOOLS_API_TOKEN="your-api-token-here"
```

The token is read from the `HETRIXTOOLS_API_TOKEN` environment variable and validated on startup. Get one from your HetrixTools account settings.

## Running

```bash
# Option 1: Direct execution (stdio transport)
uv run python server.py

# Option 2: FastMCP CLI (stdio transport)
uv run fastmcp run server.py

# Option 3: HTTP transport
uv run fastmcp run server.py --transport http --port 8000
```

## Available Tools

20 tools across 13 HetrixTools API areas:

### Account
- `get_account_limits` — current usage and limits

### Contact Lists
- `list_contact_lists` — list contact lists (paginated)

### Blacklists
- `list_blacklists` — RBLs checked by the platform
- `list_blacklist_monitors` — list blacklist monitors (filtered/paginated)
- `get_blacklist_report` — report for a specific monitor

### Uptime Monitors
- `list_uptime_monitors` — list uptime monitors (filtered/paginated)
- `get_uptime_report` — uptime report for a monitor
- `list_downtimes` — downtimes for a monitor (paginated)
- `get_location_fail_log` — fail log for a specific location
- `list_warning_policies` — list warning policies for a monitor
- `update_warning_policies` — update warning policies for a monitor

### Status Pages
- `list_status_pages` — list status pages
- `add_monitors_to_status_page` — add monitors to a status page
- `remove_monitors_from_status_page` — remove monitors from a status page

### Scheduled Maintenance
- `list_scheduled_maintenance` — list maintenance windows
- `create_scheduled_maintenance` — create a maintenance window
- `delete_scheduled_maintenance` — delete a maintenance window

### Server Agents
- `get_server_agent` — get server agent info
- `update_server_agent` — update server agent settings
- `delete_server_agent` — delete a server agent

## Architecture

- `client.py` — async HetrixTools API client (`httpx.AsyncClient`) with bearer auth, error handling for 400/401/403/404/429, and a pagination helper
- `server.py` — FastMCP server exposing all tools with type hints, docstrings, and lifespan-managed HTTP client

## Claude Desktop / MCP Client Configuration

Add to your MCP client config:

```json
{
  "mcpServers": {
    "hetrixtools": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hetrixmcp", "python", "server.py"],
      "env": {
        "HETRIXTOOLS_API_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

## Error Handling

Non-2xx responses raise `HetrixToolsError` with the HTTP status code and a descriptive message. Common errors:

| Status | Meaning |
|--------|---------|
| 400 | Bad request — check parameters |
| 401 | Unauthorized — invalid or missing API token |
| 403 | Forbidden — insufficient permissions |
| 404 | Not found — resource does not exist |
| 429 | Rate limited — retry later |