hetrixmcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hetrixmcp list my uptime monitors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: healthchecks-io-mcp
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 8000Available 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 platformlist_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 monitorlist_downtimes— downtimes for a monitor (paginated)get_location_fail_log— fail log for a specific locationlist_warning_policies— list warning policies for a monitorupdate_warning_policies— update warning policies for a monitor
Status Pages
list_status_pages— list status pagesadd_monitors_to_status_page— add monitors to a status pageremove_monitors_from_status_page— remove monitors from a status page
Scheduled Maintenance
list_scheduled_maintenance— list maintenance windowscreate_scheduled_maintenance— create a maintenance windowdelete_scheduled_maintenance— delete a maintenance window
Server Agents
get_server_agent— get server agent infoupdate_server_agent— update server agent settingsdelete_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 helperserver.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 |
Available Tools
20 toolsadd_monitors_to_status_pageA
Add monitors to a status page.
Sends a POST request with the status page ID and monitor IDs to add.
Inputs: monitor_ids (required), status_page_id (required). Returns: object
create_scheduled_maintenanceA
Create a scheduled maintenance window.
Sends a POST request with the maintenance name, start/end dates, optional affected monitor IDs, and optional description.
Inputs: name (required), end_date (required), start_date (required), description, +1 more. Returns: object
delete_scheduled_maintenanceA
Delete a scheduled maintenance window by ID.
Inputs: maintenance_id (required). Returns: object
delete_server_agentB
Delete a server agent by ID.
Inputs: agent_id (required). Returns: object
get_account_limitsA
Get current HetrixTools account usage and limits.
Returns usage and limits for uptime monitors, blacklist monitors, sub-accounts, SMS credits, account credit, and API v1/v2 access.
Inputs: no named parameters. Returns: object
get_blacklist_reportA
Get the blacklist report for a specific monitor.
Returns id, name, type, target, report_id, and a listed array
describing which RBLs currently list the target.
Inputs: identifier (required), date. Returns: object
get_location_fail_logB
Get the fail log for a specific monitoring location of an uptime monitor.
Returns a fail_log array (id, type, http_code, started_at,
ended_at, duration) plus a meta object with pagination.
Inputs: location (required), monitor_id (required), page, per_page. Returns: object
get_server_agentB
Get information for a specific server agent.
Inputs: agent_id (required). Returns: object
get_uptime_reportA
Get the uptime report for a specific monitor.
Returns timezone, per-day data (uptime, response_time, optional
hourly_stats), a summary object, and a history array.
Inputs: monitor_id (required), days, month, timezone, +1 more. Returns: object
list_blacklist_monitorsA
List blacklist monitors with optional filters and pagination.
Returns a monitors array (id, name, type, target, rdns, report_id,
status, contact_lists, listed array of {rbl, delist}, created_at,
last_check) plus a meta object with pagination info.
Inputs: cidr, name, page, type, +7 more. Returns: object
list_blacklistsA
Get the list of blacklists (RBLs) checked by the HetrixTools platform.
Returns two arrays: ipv4 and domains, each containing entries with
id, rbl name, and optional/ignored flags.
Inputs: no named parameters. Returns: object
list_contact_listsA
List contact lists configured on the account.
Each contact list includes id, name, default flag, and notification channel settings (email, phone_sms, telegram, slack, discord, webhook, and do-not-disturb settings).
Inputs: page, per_page. Returns: result
list_downtimesA
List downtimes for a specific uptime monitor.
Returns a downtimes array (id, type, http_code, location,
started_at, ended_at, duration) plus a meta object with pagination.
Inputs: monitor_id (required), page, order, per_page. Returns: object
list_scheduled_maintenanceA
List all scheduled maintenance windows.
Inputs: no named parameters. Returns: object
list_status_pagesA
List all status pages configured on the account.
Inputs: no named parameters. Returns: object
list_uptime_monitorsA
List uptime monitors with optional filters and pagination.
Returns a monitors array with detailed info: id, name, type, target,
resolve_address, port, keyword, category, timeout, check_frequency,
uptime_status, monitor_status, uptime%, locations, ssl info, domain
info, nameservers, etc.
Inputs: id, name, page, type, +7 more. Returns: object
list_warning_policiesB
List the warning policies configured for an uptime monitor.
Inputs: monitor_id (required). Returns: object
remove_monitors_from_status_pageA
Remove monitors from a status page.
Sends a DELETE request with the status page ID and monitor IDs to remove.
Inputs: monitor_ids (required), status_page_id (required). Returns: object
update_server_agentB
Update a server agent's configuration.
Sends a POST request with the provided settings dict.
Inputs: agent_id (required), settings (required). Returns: object
update_warning_policiesB
Update the warning policies for an uptime monitor.
Sends a PUT request with the provided policies array.
Inputs: policies (required), monitor_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool targets a distinct resource and action, with clear separation between list/get/update/create/delete operations. Even similar-looking tools like list_blacklists and list_blacklist_monitors are differentiated by their descriptions (RBL definitions vs monitor instances). No two tools perform the same function.
All tools follow a consistent verb_noun pattern using snake_case. Verbs (list, get, update, create, delete, add, remove) clearly indicate the operation, and nouns precisely denote the resource. There are no mixed conventions or ambiguous names.
At 20 tools, the server is slightly above the typical 3-15 well-scoped range but still reasonable given the breadth of HetrixTools' monitoring domains (uptime, blacklist, status pages, agents, maintenance, etc.). Each tool serves a distinct purpose and the count is not overwhelming.
The server is heavily read-focused, with no create/update/delete operations for the core resources (uptime monitors and blacklist monitors). While scheduled maintenance and server agents have some write support, the missing CRUD for monitors and status pages leaves significant gaps for management workflows.
Maintenance
Related MCP Connectors
Create, test, and manage uptime monitors for websites and APIs from your AI agent.
Manage scheduled requests, uptime monitors and heartbeats from your AI assistant.
Monitor websites, APIs, and servers: create monitors, triage incidents, and query uptime stats.
Manage uptime monitors and incidents and search logs, metrics and traces from an AI assistant.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with Uptime Agent monitoring system to check uptime status, manage incidents, create new monitors, and analyze downtime through natural conversation.71MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to interact with Healthchecks.io, allowing users to list, create, update, pause, resume, and delete checks, as well as view ping history and integrations.66 npm1MIT
- AlicenseAqualityBmaintenanceEnables managing Uptime Kuma monitoring through natural language, including creating, editing, pausing, and deleting monitors, plus retrieving heartbeats, status, metrics, notifications, and status pages.12MIT
- AlicenseAqualityBmaintenanceUptime monitoring your AI agent can set up: create HTTP, SSL, ping, TCP and DNS monitors checked from multiple regions, run checks on demand, read and acknowledge incidents, manage cron heartbeats, maintenance windows and status page updates.571,665 npmMIT