Cron Scheduler

npm version npm downloads MCP Claude Desktop License: MIT Tests

MCP server for cron job scheduling with SQLite persistence, retry logic, and structured observability. Let AI agents create, manage, and monitor scheduled tasks through a clean tool interface.

Why This Exists

Most cron libraries are designed for applications to embed. This server exposes cron scheduling as an MCP tool — agents can schedule jobs, monitor execution, retry failures, and query logs without touching the filesystem or crontab directly.

Companion server: System Monitoring MCP for host health metrics. Together they give agents full infrastructure observability and control.

Why This Over mcp-cron?

Feature	cron-scheduler-mcp	mcp-cron
License	MIT	AGPL-3.0
Storage	SQLite (persistent)	In-memory
Retry logic	Configurable retries with backoff	None
Observability	Success rate, avg duration, error trends	None
Systemd integration	Yes	No
Webhook triggers	Yes	No
Tool count	10	3

mcp-cron is AGPL — fine for personal use, problematic for enterprise agents and commercial deployments. This server uses MIT + SQLite persistence + retry logic for production workloads.

Features

• 10 tools: list_jobs, create_job, update_job, delete_job, get_job, run_now, get_status, get_logs, list_executions, pause_resume
• SQLite persistence — jobs survive server restarts
• Retry logic — configurable retry count and delay with attempt tracking
• Structured logs — stdout/stderr capture, duration, exit codes per execution
• Observability — success rate, average duration, error history per job
• Webhook triggers — fire HTTP callbacks on job completion
• MIT license — enterprise-friendly, no copyleft restrictions

Quick Start

npx @supernova123/cron-scheduler-mcp-server

Claude Desktop

{
  "mcpServers": {
    "cron-scheduler": {
      "command": "npx",
      "args": ["-y", "@supernova123/cron-scheduler-mcp-server"]
    }
  }
}

Cursor / VS Code

Add to your MCP settings (.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "cron-scheduler": {
      "command": "npx",
      "args": ["-y", "@supernova123/cron-scheduler-mcp-server"]
    }
  }
}

Tools

list_jobs

List all scheduled jobs with status, next run time, and last run result.

Parameter	Type	Required	Description
enabled	boolean	No	Filter by enabled/disabled status
limit	number	No	Max jobs to return (1-100)

Returns: Array of jobs with id, name, schedule, command, enabled status, next run time, last run result, and aggregate stats (success rate, total runs, avg duration).

create_job

Create a new cron job with a schedule and shell command.

Parameter	Type	Required	Description
name	string	Yes	Human-readable job name (1-128 chars)
schedule	string	Yes	Cron expression or interval (see Schedule Formats below)
command	string	Yes	Shell command to execute
enabled	boolean	No	Whether job is enabled (default: true)
retryCount	number	No	Retries on failure, 0-10 (default: 0)
retryDelayMs	number	No	Delay between retries in ms, 0-60000 (default: 1000)
timeoutMs	number	No	Execution timeout in ms, 1000-3600000 (default: 30000)

delete_job

Remove a scheduled job and its entire run history.

Parameter	Type	Required	Description
jobId	UUID	Yes	Job ID to delete

run_now

Execute a job immediately, bypassing its schedule. Useful for testing or manual triggers.

Parameter	Type	Required	Description
jobId	UUID	Yes	Job ID to execute

Returns: Run result with status, exit code, stdout/stderr (truncated to 2000 chars), and duration.

get_status

Get detailed job status including last run, next run, success rate, average duration, and recent error history.

Parameter	Type	Required	Description
jobId	UUID	Yes	Job ID to check

Returns: Full job config, next scheduled run, whether currently running, aggregate stats, and last 10 runs with status/exit code/duration.

get_logs

Get execution logs for a job with full stdout, stderr, duration, and exit code.

Parameter	Type	Required	Description
jobId	UUID	Yes	Job ID
limit	number	No	Max runs to return (1-100, default: 20)

pause_resume

Pause or resume a job without deleting it. Paused jobs retain their schedule but won't execute until resumed.

Parameter	Type	Required	Description
jobId	UUID	Yes	Job ID to pause/resume
enabled	boolean	Yes	true to resume, false to pause

Schedule Formats

• Cron expressions: Standard 5-field format
  • */5 * * * * — every 5 minutes
  • 0 9 * * 1-5 — weekdays at 9am
  • 30 2 * * 0 — Sundays at 2:30am
• Intervals: Simple duration strings
  • 30s — every 30 seconds
  • 5m — every 5 minutes
  • 1h — every hour

Use Cases

• Infrastructure automation: Schedule health checks, log rotation, cleanup scripts
• Data pipelines: Periodic data pulls, report generation, cache invalidation
• Agent workflows: Let AI agents schedule their own recurring tasks (monitoring, backups, notifications)
• DevOps: Scheduled deployments, canary checks, post-deploy verification
• Testing: Recurring integration tests, smoke checks, performance benchmarks

Configuration

Environment Variable	Default	Description
CRON_SCHEDULER_DB	cron-scheduler.db	SQLite database path (relative to CWD)

Storage

All job definitions and execution history are stored in a SQLite database. The database file persists across server restarts — jobs survive crashes and restarts without re-creation.

Blog Posts

Real data from building and running this server:

• MCP Server Testing — testing strategies for MCP servers
• What 6,000 npm Downloads Taught Me — distribution and growth data
• The MCP Server Naming Playbook — how naming affects discoverability

License

MIT