Runhooks MCP Server

Q: Do I need an API key?

Every tool except provision_account needs an API key. If you don’t have one, ask the agent to run provision_account — it creates an instant account with no email and returns a key you can save as RUNHOOKS_API_KEY.

Q: Is it open source?

Yes. @runhooks/mcp is MIT-licensed, published on npm with build provenance, and its source is mirrored to a public GitHub repository.

@runhooks/mcp is a Model Context Protocol server that lets AI agents — Claude Desktop, Cursor, and any MCP client — schedule and manage cron jobs and webhooks on Runhooks directly from your conversation.

It runs locally — your client launches it with npx, and it talks to the Runhooks REST API over HTTPS. There's no server to host and nothing to pay for beyond your normal plan usage.

npm GitHub

What it does

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to tools. Once the Runhooks MCP server is installed in your client, you can ask the agent to do things like “schedule a POST to my sync endpoint every 5 minutes” or “show the failed runs for my billing job”, and it will call the right Runhooks API for you.

Combined with instant, email-free API keys, an agent can go from zero to a running scheduled job in a single turn — no dashboard, no signup form.

No hosting. The server runs on your machine as a subprocess of your MCP client.
No new cost. It's a thin client over the Runhooks REST API; usage counts against your normal plan.
Cross-client. Works with any MCP-compatible client (Claude Desktop, Cursor, and more).

Prefer a terminal or CI? Use the Runhooks CLI. Building a direct integration? See the REST API reference.

Install

Add Runhooks to your MCP client's config. Your client spawns it with npx, so there's nothing to install globally.

json

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

Where that config lives depends on your client:

Client	Config file
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project)
Other MCP clients	Any config that accepts the `mcpServers` shape above

Restart your client after editing the config. No API key yet? See the next section.

Authentication

Every tool except provision_account needs an API key, supplied via the RUNHOOKS_API_KEY environment variable in your client config (keys are prefixed with rh_live_). There are three ways to get one:

From the agent — leave env out and ask your assistant to run the provision_account tool. It creates an instant account (no email) and returns a key. Save it as RUNHOOKS_API_KEY and restart your client.
Dashboard — register at runhooks.app/register and copy your key from Settings.
CLI — run runhooks init (see the CLI docs).

Tools

The server exposes 18 tools that mirror the Runhooks API. Your agent picks the right one from the request.

Jobs

Tool	Description
`create_job`	Create a scheduled job (cron or interval).
`list_jobs`	List jobs with optional filters and pagination.
`get_job`	Get one job by ID.
`update_job`	Update an existing job.
`delete_job`	Delete a job.
`pause_job` / `resume_job`	Pause or resume a job.

Executions

Tool	Description
`list_executions`	List a job's run history.
`replay_execution`	Re-run a past execution immediately.

Account & usage

Tool	Description
`provision_account`	Create an anonymous account and return an API key (no email, no key required to call).
`whoami`	Show the current account.
`rotate_key`	Rotate the API key.
`get_usage`	Show plan usage and limits.

Alerts

Tool	Description
`list_alerts`	List failure-alert configurations.
`create_alert`	Create a failure alert (email, webhook, or Slack).
`get_alert`	Get one alert by ID.
`update_alert`	Update an alert.
`delete_alert`	Delete an alert.

Environment Variables

Variable	Description	Default
`RUNHOOKS_API_KEY`	Your API key (`rh_live_...`). Required for all tools except `provision_account`.	—
`RUNHOOKS_API_URL`	API origin (override for self-hosted or staging).	`https://api.runhooks.app`

Example Prompts

Once installed, just talk to your agent naturally. For example:

“Create a Runhooks job that POSTs to https://api.example.com/sync every 5 minutes.”
“List my active jobs and show which one runs next.”
“Show the last 10 failed executions for my billing-sync job.”
“Pause the inventory job, then replay its most recent failed run.”
“Add an email alert to notify [email protected] after 3 consecutive failures.”
“I don't have an account yet — set one up and schedule a daily health check.”

Frequently Asked Questions

Does the Runhooks MCP server cost anything to run?

No. It uses the MCP stdio transport, so it runs locally on your machine as a subprocess of your AI client — there is no server to host. It simply calls the Runhooks REST API, and that usage counts against your normal plan like any other API call.

Do I need an API key?

Every tool except provision_account needs an API key. If you don’t have one, ask the agent to run provision_account — it creates an instant account with no email and returns a key you can save as RUNHOOKS_API_KEY.

Which AI clients are supported?

Any MCP-compatible client, including Claude Desktop and Cursor. They all use the same mcpServers configuration shape; only the location of the config file differs.

How is the MCP server different from the Runhooks CLI?

Both are thin clients over the same REST API. The CLI is for humans and scripts in a terminal; the MCP server lets an AI agent call Runhooks on your behalf from inside your editor or chat. Use whichever fits the workflow.

Is it open source?

Yes. @runhooks/mcp is MIT-licensed, published on npm with build provenance, and its source is mirrored to a public GitHub repository.