Hatchet Server

MCP server for debugging and monitoring Hatchet jobs from Claude Code or other MCP clients.

Installation

git clone https://github.com/GJakobi/hatchet-mcp.git
cd hatchet-mcp
uv sync

Configuration

Add to your .mcp.json (Claude Code) or MCP client config:

{
  "mcpServers": {
    "hatchet": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hatchet-mcp", "python", "-m", "hatchet_mcp.server"],
      "env": {
        "HATCHET_CLIENT_TOKEN": "your-hatchet-token"
      }
    }
  }
}

Available Tools

Tool	Description
list_workflows	List all registered Hatchet workflows
list_runs	List workflow runs with filters (workflow_name, status, since_hours, limit)
get_run_status	Get status of a specific run by ID
get_run_result	Get the output/result of a completed run
get_queue_metrics	Get job counts by status (queued, running, completed, failed)
search_runs	Search runs by metadata (e.g., audit_id, patient_id)

Example Usage

Once configured in Claude Code:

> List all Hatchet workflows
Uses: mcp__hatchet__list_workflows

> Show me runs that failed in the last 24 hours
Uses: mcp__hatchet__list_runs with status="failed"

> Find all runs for audit_id abc123
Uses: mcp__hatchet__search_runs with metadata_key="audit_id", metadata_value="abc123"

> What's the current queue depth?
Uses: mcp__hatchet__get_queue_metrics

Status Values

• queued - Waiting to be processed
• running - Currently executing
• completed - Finished successfully
• failed - Finished with error
• cancelled - Manually cancelled

License

MIT