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

Related MCP server: Uptime Agent MCP Server

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: