mcp-cron

MCP Cron

Model Context Protocol (MCP) server for scheduling and managing tasks through a standardized API. The server provides task scheduling capabilities supporting both shell commands and AI-powered tasks, all accessible via the MCP protocol.

Features

• Schedule shell command or prompt to AI tasks using cron expressions
• AI can have access to MCP servers
• Manage tasks via MCP protocol
• Task execution with command output capture

Installation

Building from Source

Prerequisites

• Go 1.23.0 or higher

# Clone the repository
git clone https://github.com/jolks/mcp-cron.git
cd mcp-cron

# Build the application as mcp-cron binary
go build -o mcp-cron cmd/mcp-cron/main.go

Usage

The server supports two transport modes:

• SSE (Server-Sent Events): Default HTTP-based transport for browser and network clients
• stdio: Standard input/output transport for direct piping and inter-process communication

SSE

# Start the server with HTTP SSE transport (default mode)
# Default to localhost:8080
./mcp-cron

# Start with custom address and port
./mcp-cron --address 127.0.0.1 --port 9090

Config file example

{
  "mcpServers": {
    "mcp-cron": {
      "url": "http://localhost:8080/sse"
    }
  }
}

stdio

The stdio transport is particularly useful for:

• Claude Desktop which does not officially support SSE yet. See https://github.com/orgs/modelcontextprotocol/discussions/16
• Direct piping to/from other processes
• Integration with CLI tools
• Testing in environments without HTTP
• Docker container integration

Upon starting Cursor IDE and Claude Desktop, it will automatically start the server

Config file example

{
  "mcpServers": {
    "mcp-cron": {
      "command": "<path to where mcp-cron binary is located>/mcp-cron",
      "args": ["--transport", "stdio"]
    }
  }
}

Command Line Arguments

The following command line arguments are supported:

Environment Variables

The following environment variables are supported:

Logging

When running with the default SSE transport, logs are output to the console.

When running with stdio transport, logs are redirected to a mcp-cron.log log file to prevent interference with the JSON-RPC protocol:

• Log file location: Same location as mcp-cron binary.
• Task outputs, execution details, and server diagnostics are written to this file.
• The stdout/stderr streams are kept clean for protocol messages only.

Available MCP Tools

The server exposes several tools through the MCP protocol:

1. list_tasks - Lists all scheduled tasks
2. get_task - Gets a specific task by ID
3. add_task - Adds a new scheduled task
4. add_ai_task - Adds a new scheduled AI (LLM) task with a prompt
5. update_task - Updates an existing task
6. remove_task - Removes a task by ID
7. enable_task - Enables a disabled task
8. disable_task - Disables an enabled task

Task Format

Tasks have the following structure:

{
  "id": "task_1234567890",
  "name": "Example Task",
  "schedule": "0 */5 * * * *",
  "command": "echo 'Task executed!'",
  "prompt": "Analyze yesterday's sales data and provide a summary",
  "type": "shell_command",
  "description": "An example task that runs every 5 minutes",
  "enabled": true,
  "lastRun": "2025-01-01T12:00:00Z",
  "nextRun": "2025-01-01T12:05:00Z",
  "status": "completed",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T12:00:00Z"
}

For shell command tasks, use the command field to specify the command to execute. For AI tasks, use the prompt field to specify what the AI should do. The type field can be either shell_command (default) or AI.

Task Status

The tasks can have the following status values:

• pending - Task has not been run yet
• running - Task is currently running
• completed - Task has successfully completed
• failed - Task has failed during execution
• disabled - Task is disabled and won't run on schedule

Cron Expression Format

The scheduler uses the github.com/robfig/cron/v3 library for parsing cron expressions. The format includes seconds:

┌───────────── second (0 - 59) (Optional)
│ ┌───────────── minute (0 - 59)
│ │ ┌───────────── hour (0 - 23)
│ │ │ ┌───────────── day of the month (1 - 31)
│ │ │ │ ┌───────────── month (1 - 12)
│ │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
│ │ │ │ │ │
│ │ │ │ │ │
* * * * * *

Examples:

• 0 */5 * * * * - Every 5 minutes (at 0 seconds)
• 0 0 * * * * - Every hour
• 0 0 0 * * * - Every day at midnight
• 0 0 12 * * MON-FRI - Every weekday at noon

Development

Project Structure

mcp-cron/
├── cmd/
│   └── mcp-cron/        # Main application entry point
├── internal/
│   ├── agent/           # AI agent execution functionality 
│   ├── command/         # Command execution functionality
│   ├── config/          # Configuration handling
│   ├── errors/          # Error types and handling
│   ├── logging/         # Logging utilities
│   ├── model/           # Data models and types
│   ├── scheduler/       # Task scheduling
│   ├── server/          # MCP server implementation
│   └── utils/           # Miscellanous utilities
├── scripts/             # Utility scripts
├── go.mod               # Go modules definition
├── go.sum               # Go modules checksums
└── README.md            # Project documentation

Building and Testing

# Build the application
go build -o mcp-cron cmd/mcp-cron/main.go

# Run tests
go test ./...

# Run tests and check coverage
go test ./... -cover

Acknowledgments

• ThinkInAIXYZ/go-mcp - Go SDK for the Model Context Protocol
• robfig/cron - Cron library for Go