cronmcp

cronmcp is an open-source cron scheduler stdio MCP server built on top of cron, cron-parser, commander, and @modelcontextprotocol/sdk.

It lets MCP-compatible clients create and manage scheduled prompt jobs, and optionally subscribe to cron tick notifications through an MCP notification channel.

Highlights

• Exposes cron scheduling as an MCP server over stdio.

• Uses the cron package for in-process job execution.

• Validates schedules as 5-field local cron (M H DoM Mon DoW).

• Persists jobs in JSONL under ~/.cronmcp/crontab.

• Provides tools to list, add, update, and remove jobs.

• Supports one-shot schedules through once: true.

• Can emit scheduled tick events over an optional MCP notification channel.

Related MCP server: silentwatch-mcp

Requirements

• Node.js 24+

Installation

Use it without installing globally:

npx cronmcp mcp

Or for local development:

npm install
npm run build
npm run dev -- mcp

Quick Start

1. Start the MCP server:

npx cronmcp mcp

2. If your MCP host supports notifications and you want tick events, enable channels:

npx cronmcp mcp --channels

The server uses stdio, so it is meant to be launched by an MCP client or wrapper rather than browsed directly in a terminal.

CLI Usage

MCP Server

npx cronmcp mcp

Starts the stdio MCP server with job persistence at ~/.cronmcp/crontab.

MCP Tools

The server currently exposes these tools:

• cron_list_jobs

• cron_add_job

• cron_update_job

• cron_remove_job

schedule values use local-time 5-field cron: minute hour day-of-month month day-of-week.

Push Channel

When started with --channels, the server:

• advertises the experimental MCP capability hooman/channel

• advertises hooman/user with path meta.user

• advertises hooman/session with path meta.session

• advertises hooman/thread with path meta.thread

• emits notifications/hooman/channel for scheduled cron tick events

Each notification includes:

• content: a JSON-encoded event payload

• meta.source: cron (channel contract)

• meta.user: scheduler

• meta.session: the cron job ID

• meta.thread: omitted for cron tick events

The JSON-decoded content payload includes:

• source

• job

• prompt

• tickedAt

Local Data

cronmcp stores local state under ~/.cronmcp/:

• crontab for JSONL job records

Each record shape:

{
  "id": "job_34a56f84-cf7e-4f8d-810c-1777d9f4a5f1",
  "schedule": "*/5 * * * *",
  "prompt": "Check queue depth",
  "once": false,
  "createdAt": 1777098600000
}

Notes

• Cron expressions must be valid 5-field local schedules.

• Jobs must have a next run within the next year.

• At most 50 jobs can be scheduled at once.

• Recurring jobs auto-expire after 7 days (they fire one final time, then are removed).

• Recurring jobs use deterministic jitter to avoid synchronized fire spikes.

• once: true jobs are removed after the first successful tick.

• Incoming notification channels depend on MCP host support.

License

MIT. See LICENSE.