Cronmcp

npm version Publish to NPM License: MIT

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.

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.