Runhooks README

@runhooks/mcp

Model Context Protocol (MCP) server for Runhooks — reliable HTTP scheduling infrastructure. It lets AI agents (Claude Desktop, Cursor, and any MCP client) schedule and manage recurring and one-off HTTP jobs directly.

The server runs locally on your machine: your MCP client spawns it with npx and it talks to the Runhooks REST API over HTTPS. There is no hosted service — just this package.

Install

Add it to your MCP client config. For Claude Desktop (claude_desktop_config.json):

config.json

{
  "mcpServers": {
    "runhooks": {
      "command": "npx",
      "args": ["-y", "@runhooks/mcp"],
      "env": { "RUNHOOKS_API_KEY": "rh_live_..." }
    }
  }
}

No API key yet? Leave env out and ask the agent to run the provision_account tool once — it creates an instant account (no email), returns an rh_live_... key, and saves it locally to ~/.runhooks/mcp.json. The key is reused automatically from then on, so every other tool works immediately with no restart and no need to provision again. (Setting RUNHOOKS_API_KEY is still the most portable option across machines, and it always takes precedence over the saved key.)

Verify

Check the server starts and advertises its tools (replace the key, or omit env and use provision_account from inside your client):

bash

RUNHOOKS_API_KEY=rh_live_... npx -y @runhooks/mcp

Environment variables

Variable	Description	Default
`RUNHOOKS_API_KEY`	Your API key (`rh_live_...`). Optional — `provision_account` saves a key locally if unset. Takes precedence over the saved key.	—
`RUNHOOKS_API_URL`	API origin.	`https://api.runhooks.app`

Tools

Tool	Description
`provision_account`	Create an anonymous account and get an API key (no email).
`whoami`	Show the current account.
`rotate_key`	Rotate the API key.
`create_job`	Create a scheduled job (cron or interval).
`list_jobs`	List jobs with filters and pagination.
`get_job`	Get one job by ID.
`update_job`	Update a job.
`delete_job`	Delete a job.
`pause_job` / `resume_job`	Pause or resume a job.
`list_executions`	List a job's run history.
`replay_execution`	Re-run a past execution.
`get_usage`	Show plan usage and limits.
`list_alerts` / `create_alert` / `get_alert` / `update_alert` / `delete_alert`	Manage failure alerts (email, webhook, Slack).

License

MIT