Allows AI agents to schedule and manage recurring or one-off HTTP jobs via the Runhooks API.
Also known as runhooks/runhooks-mcp, runhooks-mcp, @runhooks/mcp
- Stars
- 0
- Tools
- 11
- Downloads, 30 days
- —
- Latest version
- 0.1.12
- Last commit
- Nov 8, 2026
- License
- MIT
What is Runhooks MCP?
Runhooks allows AI agents to schedule and manage recurring or one-off HTTP jobs via the Runhooks API. It exposes 11 tools, such as provision_account, whoami, rotate_key.
Summary generated from the project's README
About Runhooks MCP server
Runhooks provides a way for AI agents to manage HTTP job scheduling through a local MCP server. Developers using clients like Claude Desktop or Cursor can use this package to orchestrate both recurring tasks via cron or intervals and one-off executions at specific future times. The server runs on your machine using npx and communicates with the Runhooks REST API over HTTPS.
Setting up the server is straightforward. You can provide a RUNHOOKS_API_KEY in your environment variables, or simply use the provision_account tool to create an anonymous account without an email address. Once provisioned, the API key is saved to ~/.runhooks/mcp.json for automatic reuse. The server includes tools to manage the entire lifecycle of a job, including pausing, resuming, deleting, and replaying past executions. It also allows for monitoring plan usage and configuring failure alerts via email, webhooks, or Slack.
What you can do with it
- 1Automate recurring HTTP requestsSchedule a job to run at specific intervals or using cron syntax.
- 2Handle job execution failuresSet up notifications to be alerted when a scheduled task fails.
Written from the project's README. Every use case is checked against a quote from it.
How to install Runhooks MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Runhooks MCP in Claude Code
$ claude mcp add --env 'RUNHOOKS_API_KEY=<YOUR_RUNHOOKS_API_KEY>' runhooks-mcp -- npx -y @runhooks/mcpInstall Runhooks MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"runhooks-mcp": {
"command": "npx",
"args": [
"-y",
"@runhooks/mcp"
],
"env": {
"RUNHOOKS_API_KEY": "<YOUR_RUNHOOKS_API_KEY>"
}
}
}
}Install Runhooks MCP in VS Code
.vscode/mcp.json
{
"servers": {
"runhooks-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@runhooks/mcp"
],
"env": {
"RUNHOOKS_API_KEY": "<YOUR_RUNHOOKS_API_KEY>"
}
}
}
}Install Runhooks MCP in VS Code CLI
$ code --add-mcp '{"name":"runhooks-mcp","type":"stdio","command":"npx","args":["-y","@runhooks/mcp"],"env":{"RUNHOOKS_API_KEY":"<YOUR_RUNHOOKS_API_KEY>"}}'Install Runhooks MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"runhooks-mcp": {
"command": "npx",
"args": [
"-y",
"@runhooks/mcp"
],
"env": {
"RUNHOOKS_API_KEY": "<YOUR_RUNHOOKS_API_KEY>"
}
}
}
}Install Runhooks MCP in Codex
$ codex mcp add runhooks-mcp --env 'RUNHOOKS_API_KEY=<YOUR_RUNHOOKS_API_KEY>' -- npx -y @runhooks/mcpInstall Runhooks MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.runhooks-mcp] command = "npx" args = ["-y", "@runhooks/mcp"] [mcp_servers.runhooks-mcp.env] RUNHOOKS_API_KEY = "<YOUR_RUNHOOKS_API_KEY>"
Install Runhooks MCP in Gemini CLI
$ gemini mcp add -s user -e 'RUNHOOKS_API_KEY=<YOUR_RUNHOOKS_API_KEY>' runhooks-mcp npx -- -y @runhooks/mcpInstall Runhooks MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"runhooks-mcp": {
"command": "npx",
"args": [
"-y",
"@runhooks/mcp"
],
"env": {
"RUNHOOKS_API_KEY": "<YOUR_RUNHOOKS_API_KEY>"
}
}
}
}Runhooks MCP tools 11
Detected from the READMEprovision_accountwhoamirotate_keycreate_joblist_jobsget_jobupdate_jobdelete_joblist_executionsreplay_executionget_usage
| provision_account | — | |
| whoami | — | |
| rotate_key | — | |
| create_job | — | |
| list_jobs | — | |
| get_job | — | |
| update_job | — | |
| delete_job | — | |
| list_executions | — | |
| replay_execution | — | |
| get_usage | — |
Configuration
RUNHOOKS_API_KEYSecretRunhooks API key (rh_live_...). Required for all tools except provision_account; get one instantly with the provision_account tool, the dashboard, or the CLI.
RUNHOOKS_API_URLAPI origin override. Defaults to https://api.runhooks.app.
| Name | Description | |
|---|---|---|
| RUNHOOKS_API_KEY | Runhooks API key (rh_live_...). Required for all tools except provision_account; get one instantly with the provision_account tool, the dashboard, or the CLI. | Secret |
| RUNHOOKS_API_URL | API origin override. Defaults to https://api.runhooks.app. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablerunhooks/runhooks-mcp is public and reachablegithub.com/runhooks/runhooks-mcp ↗Pass
- Package names this repository as its source@runhooks/mcp names runhooks/runhooks-mcp as sourcenpmjs.com/package/@runhooks/mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @runhooks/mcpnpmjs.com/package/@runhooks/mcp/v/0.1.12#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/runhooks/runhooks-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @runhooks/mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model11 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@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):
{
"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):
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 — recurring (cron or interval) or a one-off run at a future date-time (once). |
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). |
Links
- Documentation: https://runhooks.app/docs/mcp
- API reference: https://runhooks.app/docs/api
- CLI: https://www.npmjs.com/package/@runhooks/cli
License
MIT
Runhooks MCP questions
How do I add Runhooks MCP to Claude Code?
Run claude mcp add --env 'RUNHOOKS_API_KEY=<YOUR_RUNHOOKS_API_KEY>' runhooks-mcp -- npx -y @runhooks/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Runhooks MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Runhooks MCP provide?
It exposes 11 tools, including provision_account, whoami, rotate_key, create_job, list_jobs.
How do I get an API key?
You can ask your agent to run the provision_account tool, which creates an anonymous account and returns an API key.
Does the server require a hosted service?
No, the server runs locally on your machine and communicates with the Runhooks REST API over HTTPS.
Can I schedule recurring jobs?
Yes, you can create scheduled jobs that are either recurring using cron or intervals, or one-off runs at a specific future time.