Skip to main content
Glama

MCP Cron Server

MCP Cron Server is a standalone scheduling service that provides cron-like job scheduling through the Model Context Protocol (MCP). It integrates with OpenCode, allowing users to manage scheduled tasks using natural language.

Features

  • Three Schedule Types: One-time (at), Interval (every), Cron Expression

  • SQLite Persistence: WAL mode for high-concurrency read/write

  • Approval System: Jobs can require manual approval before execution

  • Heartbeat Mechanism: Automatic zombie task detection

  • Execution State Machine: Complete state transitions (pending → running → success/failed/waiting_for_approval/paused/cancelled)

  • Automatic Error Backoff: 30s → 1m → 5m → 15m → 60m

  • Concurrency Control: Max 3 concurrent executions

  • Execution Logs: Buffered logging to avoid blocking

Related MCP server: Schedule Task MCP

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     OpenCode CLI                             │
│                         │                                    │
│         ┌───────────────┴───────────────┐                   │
│         ▼                               ▼                   │
│  ┌──────────────┐              ┌──────────────┐            │
│  │   MCP Client │              │    Skill     │            │
│  │   (14 tools) │              │  (mcp-cron)  │            │
│  └──────────────┘              └──────────────┘            │
└─────────────────────────────────────────────────────────────┘
          │ stdio
          ▼
┌─────────────────────────────────────────────────────────────┐
│                  MCP Cron Server                            │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  CronScheduler                       │   │
│  │  ┌─────────────┐  ┌─────────┐  ┌──────────────┐  │   │
│  │  │ Repository   │  │  Timer  │  │   Executor   │  │   │
│  │  │  (SQLite)   │  │(setTimeout)│ │(subprocess) │  │   │
│  │  │ +LogBuffer  │  └─────────┘  └──────────────┘  │   │
│  │  └─────────────┘                                    │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Project Structure

opencode-mcp-cron/
├── package.json              # Project configuration
├── tsconfig.json            # TypeScript configuration
└── src/
    ├── index.ts             # MCP server entry point
    ├── types.ts            # Type definitions
    ├── database.ts          # SQLite database management
    ├── repository.ts        # Data access layer (with log buffer)
    ├── scheduler.ts         # Scheduler
    ├── executor.ts          # Execution engine
    └── schedule.ts          # Schedule time calculation

Type Definitions

Schedule Types

type CronSchedule =
  | { kind: 'at'; atMs: number }                    // One-time task
  | { kind: 'every'; everyMs: number; anchorMs?: number }  // Interval task
  | { kind: 'cron'; expr: string; tz?: string };     // Cron expression

Payload Types

type CronPayload = {
  kind: 'agentTurn' | 'systemEvent';
  message: string;           // Prompt or message content
  deliver?: boolean;         // Whether to deliver result
  channel?: string;         // Delivery channel
  to?: string;              // Delivery target
  model?: string;           // Model override
};

Execution Status

type ExecutionStatus = 
  | 'pending'              // Waiting to execute
  | 'running'              // Currently executing
  | 'success'              // Executed successfully
  | 'failed'               // Execution failed
  | 'waiting_for_approval' // Waiting for approval
  | 'paused'               // Paused
  | 'cancelled';          // Cancelled

Core Components

1. Database (database.ts)

SQLite database management.

Features:

  • WAL mode for high-concurrency read/write

  • Automatic schema migration

  • Prepared statement caching

  • Location: ~/.local/share/mcp-cron/cron.db

2. Repository (repository.ts)

Data access layer.

Features:

  • Job/Execution/Log/Approval CRUD

  • Log buffering (batch writes to avoid blocking)

  • Atomic state transitions

  • Prepared statements

3. Schedule (schedule.ts)

Schedule time calculation.

Functions:

// Calculate next execution time
computeNextRunAtMs(schedule: CronSchedule, nowMs: number): number | undefined

// Format time for display
formatNextRun(nextRunAtMs: number | undefined): string

4. Scheduler (scheduler.ts)

Main scheduler.

Features:

  • Dynamic sleep scheduling

  • Batch rate limiting

  • State machine driven

  • Concurrency control

  • Zombie task detection

5. Executor (executor.ts)

Job execution engine.

Features:

  • Subprocess execution

  • Streaming logs

  • Heartbeat updates

  • Timeout control

  • Approval triggering

MCP Tools

Tool

Description

cron_add

Add a new scheduled job

cron_list

List all jobs

cron_get

Get job details

cron_update

Update a job

cron_remove

Delete a job

cron_run

Execute a job immediately

cron_status

Get scheduler status

cron_get_approvals

Get pending approvals

cron_approve

Approve execution

cron_reject

Reject execution

cron_get_logs

Get execution logs

cron_get_stats

Get system statistics

cron_get_history

Get execution history

cron_list_executions

List executions with pagination

Usage

Build

cd ~/Documents/opencode-mcp-cron
npm install
npm run build

Configuration

Add to OpenCode configuration:

{
  "mcp": {
    "cron": {
      "type": "local",
      "command": ["node", "/path/to/dist/index.js"],
      "enabled": true
    }
  }
}

Cron Expression Examples

Expression

Description

0 8 * * *

Every day at 8:00 AM

0 9 * * 1-5

Weekdays at 9:00 AM

0 18 * * 1-5

Weekdays at 6:00 PM

0 */2 * * *

Every 2 hours

0 0 * * *

Daily at midnight

Data Storage

  • Database: ~/.local/share/mcp-cron/cron.db

  • Logs: Stored in SQLite logs table

Environment Variables

Variable

Description

Default

OPENCODE_COMMAND

opencode command path

opencode

MCP_CRON_DB_PATH

Database path

~/.local/share/mcp-cron/cron.db

Troubleshooting

Job Not Executing

  1. Check scheduler status:

opencode run "use cron_status tool to check scheduler status"
  1. List jobs:

opencode run "use cron_list tool to list all jobs"
  1. Check execution logs:

opencode run "use cron_get_logs tool to view logs"

MCP Server Connection Failed

  1. Verify configuration path

  2. Test server manually:

node ~/Documents/opencode-mcp-cron/dist/index.js

Last updated: 2026-03-10

Available Tools

5 tools
cron_addC

添加定时任务

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes任务名称
descriptionNo任务描述(可选)
scheduleYes调度配置
payloadYes任务内容
optionsNo

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. '添加定时任务' indicates a write operation that creates a scheduled task, but it doesn't disclose any behavioral traits such as authentication requirements, rate limits, side effects, error conditions, or what happens on success/failure. For a mutation tool with complex parameters and no annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at just four characters ('添加定时任务'), which translates to 'Add scheduled task'. It's front-loaded with the core action and resource, with zero wasted words. For a tool with a clear name like cron_add, this minimal description efficiently communicates the purpose without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters with nested objects, mutation operation, no output schema, and no annotations), the description is insufficiently complete. It doesn't explain what the tool returns, error conditions, or behavioral constraints. While the schema provides good parameter documentation, the description fails to address the broader context needed for a mutation tool that creates scheduled tasks with potentially significant system impact.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no parameter-specific information beyond what's already in the schema. With 80% schema description coverage, the schema documents most parameters well (name, description, schedule configuration, payload, options). The description doesn't explain relationships between parameters, provide examples, or clarify semantics beyond the schema. This meets the baseline of 3 when schema coverage is high, but doesn't compensate for the remaining 20% gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description '添加定时任务' (Add scheduled task) clearly states the verb 'add' and resource 'scheduled task', making the purpose immediately understandable. It distinguishes from siblings like cron_list (list), cron_remove (remove), cron_run (run), and cron_status (status) by specifying the creation action. However, it doesn't specify what kind of scheduled tasks are being added beyond the generic term.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when cron_add is appropriate versus cron_run or cron_status, or any constraints on usage. The agent must infer usage from the tool name and sibling names alone, which is insufficient for informed tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cron_listB

列出所有定时任务

ParametersJSON Schema
NameRequiredDescriptionDefault
includeDisabledNo包含禁用的任务

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states it lists tasks but doesn't mention whether this requires authentication, what format the output takes (e.g., list, table, JSON), if there are rate limits, or how disabled tasks are handled (though the parameter covers this partially). This leaves significant gaps for an agent to understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence in Chinese that directly states the tool's purpose with zero wasted words. It's appropriately front-loaded and earns its place by clearly conveying the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one optional parameter, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks details on output format, authentication, or error handling, which would be helpful for an agent to use it correctly in context with sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents the single parameter (includeDisabled). The description adds no additional parameter information beyond what's in the schema, but since the schema is complete, the baseline score of 3 is appropriate as the description doesn't need to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description '列出所有定时任务' (List all scheduled tasks) clearly states the verb ('list') and resource ('scheduled tasks'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like cron_status (which might check status of specific tasks) or cron_run (which executes tasks), but the 'all' scope provides some implicit distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like cron_status or cron_add. The description implies it's for listing tasks, but there's no explicit mention of prerequisites, when this should be used over other listing methods, or any contextual limitations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cron_removeC

删除定时任务

ParametersJSON Schema
NameRequiredDescriptionDefault
jobIdYes任务ID

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. '删除定时任务' implies a destructive mutation, but it doesn't specify whether deletion is permanent, requires specific permissions, has side effects (e.g., stopping running tasks), or provides confirmation feedback. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single phrase '删除定时任务', which is extremely concise and front-loaded with the core action. There is zero wasted language, making it efficient for quick comprehension without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity as a destructive operation with no annotations and no output schema, the description is incomplete. It lacks critical context such as what happens post-deletion, error conditions, or return values. For a mutation tool, this leaves the agent with insufficient information to use it safely and effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with 'jobId' clearly documented as '任务ID' (task ID). The description doesn't add any parameter details beyond what the schema provides, such as format examples or where to obtain the ID. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description '删除定时任务' (delete scheduled task) clearly states the verb (delete) and resource (scheduled task), making the purpose immediately understandable. It distinguishes from siblings like cron_add (add), cron_list (list), cron_run (run), and cron_status (check status) by specifying the destructive action. However, it doesn't specify whether this deletes by ID or other criteria, which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid jobId), when not to use it (e.g., if the task is currently running), or how it relates to sibling tools like cron_list to find IDs first. This leaves the agent with minimal context for proper tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cron_runC

立即执行定时任务

ParametersJSON Schema
NameRequiredDescriptionDefault
jobIdYes任务ID

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool executes a task immediately, but doesn't disclose behavioral traits such as whether this requires specific permissions, what happens if the task is already running, if execution is synchronous or asynchronous, error handling, or rate limits. For a mutation tool with zero annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient phrase ('立即执行定时任务') that directly states the purpose. It's front-loaded with no unnecessary words, making it highly concise and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a mutation operation with no annotations and no output schema), the description is incomplete. It lacks details on behavioral aspects like permissions, execution mode, error responses, and how it interacts with sibling tools. The description alone doesn't provide enough context for safe and effective use by an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the single parameter 'jobId' documented as '任务ID' (task ID). The description doesn't add any meaning beyond what the schema provides, such as format examples or where to find the ID. With high schema coverage, the baseline is 3, and the description doesn't compensate with extra details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description '立即执行定时任务' (immediately execute scheduled task) clearly states the action (execute) and resource (scheduled task). It distinguishes from siblings like cron_add (add), cron_list (list), cron_remove (remove), and cron_status (check status) by focusing on execution. However, it doesn't specify what 'immediately' means relative to normal scheduling, which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., the task must exist), exclusions (e.g., cannot execute if already running), or comparisons to siblings like cron_status for checking task state. Usage is implied but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cron_statusC

获取调度器状态

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('get scheduler status') but doesn't describe what the status includes (e.g., uptime, active jobs, errors), whether it's read-only or has side effects, or any rate limits or authentication needs. This is a significant gap for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient phrase ('获取调度器状态') that directly states the tool's purpose with zero waste. It's appropriately sized for a simple, parameter-less tool and is front-loaded with essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no output schema), the description is minimal but adequate for basic understanding. However, it lacks details on what 'status' entails, behavioral traits (since no annotations exist), and differentiation from siblings, making it incomplete for optimal agent use in a context with multiple cron-related tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter semantics, and a baseline score of 4 is appropriate as it avoids redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description '获取调度器状态' (Get scheduler status) clearly states the verb ('get') and resource ('scheduler status'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'cron_list' (which might list cron jobs) or 'cron_run' (which might execute a cron job), leaving some ambiguity about what specific 'status' information is provided.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'cron_list' or 'cron_run'. It doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage based on the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv1.0.0
    • First observedcron_add
    • First observedcron_list
    • First observedcron_remove
    • First observedcron_run
    • First observedcron_status

TDQS

A3.5/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: add, list, remove, run, and status cover different aspects of cron job management. The descriptions are straightforward and prevent any confusion between tools.

Naming Consistency5/5

All tool names follow a consistent 'cron_verb' pattern (e.g., cron_add, cron_list), using snake_case throughout. This predictable naming makes it easy to understand and navigate the tool set.

Tool Count5/5

With 5 tools, this server is well-scoped for managing cron jobs, covering essential operations without being overly complex or sparse. Each tool serves a clear and necessary function in the domain.

Completeness5/5

The tool set provides complete CRUD/lifecycle coverage for cron job management: add, list, remove, run, and status. There are no obvious gaps, allowing agents to handle all typical workflows without dead ends.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    A robust task scheduler server built with Model Context Protocol for scheduling and managing various types of automated tasks including shell commands, API calls, AI tasks, and reminders.
    4
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables creation and management of scheduled tasks with interval, cron, or one-time triggers. Persists tasks in SQLite and supports MCP sampling to automatically invoke AI agents when schedules trigger.
    16
    3
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server for scheduling and executing Claude Code CLI tasks via cron expressions, featuring a web dashboard and webhook support. It enables users to dynamically create custom MCP servers, manage recurring AI jobs, and track execution history with token and cost analytics.
    24
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    An MCP server that surfaces scheduled-job state and detects silent failures (exit 0 but no useful output) for cron, systemd timers, and OpenClaw schedulers, enabling AI agents to query job health and overdue status directly.
    6
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nolan57/opencode-mcp-cron'

If you have feedback or need assistance with the MCP directory API, please join our Discord server