README.md
MCP server for debugging and monitoring Hatchet jobs
Hatchet MCP 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 processedrunning- Currently executingcompleted- Finished successfullyfailed- Finished with errorcancelled- Manually cancelled
License
MIT
Tools (6)
list_workflowsList all registered Hatchet workflowslist_runsList workflow runs with filtersget_run_statusGet status of a specific run by IDget_run_resultGet the output/result of a completed runget_queue_metricsGet job counts by statussearch_runsSearch runs by metadataEnvironment Variables
HATCHET_CLIENT_TOKENrequiredAuthentication token for the Hatchet APIConfiguration
claude_desktop_config.json
{"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"}}}}Try it
→List all registered Hatchet workflows.
→Show me all workflow runs that failed in the last 24 hours.
→Find all runs associated with audit_id abc123.
→What is the current queue depth for my Hatchet jobs?
→Get the result for the completed run with ID 12345.