Manual setup required. The maintainer's config contains paths only you know - edit the placeholders below before adding it to Claude Code.
1
Prepare the server locally
Run this once before adding it to Claude Code.
git clone https://github.com/GJakobi/hatchet-mcp.git
cd hatchet-mcp
uv sync2
Register it in Claude Code
claude mcp add -e "HATCHET_CLIENT_TOKEN=${HATCHET_CLIENT_TOKEN}" hatchet -- uv run --directory /path/to/hatchet-mcp python -m hatchet_mcp.serverReplace any placeholder paths in the command with the real path on your machine.
Required:
HATCHET_CLIENT_TOKEN3
Make your agent remember this setup
hatchet's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- List and monitor registered Hatchet workflows
- Filter and track workflow run statuses
- Retrieve specific job outputs and results
- Query real-time queue metrics by job status
- Search for runs using custom metadata keys
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 APITry 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.
Original README from GJakobi/hatchet-mcp
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