hetrixmcp

A Model Context Protocol server for the HetrixTools API v3, built with FastMCP.

Requirements

• Python 3.14+
• uv for package management
• A HetrixTools API token

Setup

# 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

# 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:

{
  "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