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
MCP server for scheduling and running AI prompts, HTTP/webhook requests, and shell commands
The --ai-model value should match a model name in your LiteLLM proxy config. LiteLLM exposes an OpenAI-compatible API, so --ai-provider can be omitted (defaults to openai). When a custom base URL is set, mcp-cron automatically uses the Chat Completions API instead of the Responses API. The Responses API is only used for direct OpenAI (api.openai.com) and Azure OpenAI (*.openai.azure.com) endpoints.
# 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:
HTTP (Streamable HTTP): Default HTTP-based transport for browser and network clients
stdio: Standard input/output transport for direct piping and inter-process communication
# Start the server with Streamable HTTP transport (default mode)
# Default to localhost:8080
./mcp-cron
# Start with custom address and port
./mcp-cron --address 127.0.0.1 --port 9090
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:
Argument
Description
Default
--address
The address to bind the server to
localhost
--port
The port to bind the server to
8080
--transport
Transport mode: http or stdio
http
--log-level
Logging level: debug, info, warn, error, fatal
info
--log-file
Log file path
stdout
--version
Show version information and exit
false
--ai-provider
AI provider: openai or anthropic
openai
--ai-base-url
Custom base URL for OpenAI-compatible endpoints (e.g. Ollama, vLLM, Groq, LiteLLM)
Not set
--ai-model
AI model to use for AI tasks
gpt-4o
--ai-max-iterations
Maximum iterations for tool-enabled AI tasks
20
--mcp-config-path
Path to MCP configuration file
~/.cursor/mcp.json
--db-path
Path to SQLite database for result history
~/.mcp-cron/results.db
--prevent-sleep
Prevent system from sleeping while mcp-cron is running (macOS and Windows)
false
--poll-interval
How often to check for due tasks
1s
Environment Variables
The following environment variables are supported:
Environment Variable
Description
Default
MCP_CRON_SERVER_ADDRESS
The address to bind the server to
localhost
MCP_CRON_SERVER_PORT
The port to bind the server to
8080
MCP_CRON_SERVER_TRANSPORT
Transport mode: http or stdio
http
MCP_CRON_SERVER_NAME
Deprecated — ignored; the server name is fixed to ensure self-reference detection works correctly
-
MCP_CRON_SERVER_VERSION
Deprecated — ignored; version is set at build time via ldflags
-
MCP_CRON_SCHEDULER_DEFAULT_TIMEOUT
Default timeout for task execution
10m
MCP_CRON_LOGGING_LEVEL
Logging level: debug, info, warn, error, fatal
info
MCP_CRON_LOGGING_FILE
Log file path
stdout
MCP_CRON_AI_PROVIDER
AI provider: openai or anthropic
openai
MCP_CRON_AI_BASE_URL
Custom base URL for OpenAI-compatible endpoints (e.g. Ollama, vLLM, Groq, LiteLLM)
Not set
MCP_CRON_AI_API_KEY
Generic fallback API key (used when provider-specific key is not set)
Not set
OPENAI_API_KEY
OpenAI API key for AI tasks
Not set
ANTHROPIC_API_KEY
Anthropic API key for AI tasks
Not set
MCP_CRON_ENABLE_OPENAI_TESTS
Enable OpenAI integration tests
false
MCP_CRON_AI_MODEL
LLM model to use for AI tasks
gpt-4o
MCP_CRON_AI_MAX_TOOL_ITERATIONS
Maximum iterations for tool-enabled tasks
20
MCP_CRON_MCP_CONFIG_FILE_PATH
Path to MCP configuration file
~/.cursor/mcp.json
MCP_CRON_STORE_DB_PATH
Path to SQLite database for result history
~/.mcp-cron/results.db
MCP_CRON_PREVENT_SLEEP
Prevent system from sleeping while mcp-cron is running (macOS and Windows)
false
MCP_CRON_POLL_INTERVAL
How often to check for due tasks (Go duration format)
1s
Sleep Prevention
On laptops, the system may go to sleep and prevent scheduled tasks from running on time. Use the --prevent-sleep flag to keep the system awake while mcp-cron is running:
Prevents idle sleep; automatically cleans up on exit
Windows
SetThreadExecutionState
Prevents idle sleep; automatically cleans up on exit
Linux
Not supported
Linux servers typically do not auto-sleep
Note: This prevents idle sleep only. It does not prevent sleep from closing the laptop lid or pressing the power button.
Logging
When running with the default HTTP 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:
list_tasks - Lists all tasks (scheduled and on-demand)
get_task - Gets a specific task by ID
add_task - Adds a new shell command task (provide schedule for recurring, or omit for on-demand)
add_ai_task - Adds a new AI (LLM) task with a prompt (provide schedule for recurring, or omit for on-demand)
add_http_task - Adds a new HTTP (webhook) task that issues an HTTP request to a url (provide schedule for recurring, or omit for on-demand)
update_task - Updates an existing task
remove_task - Removes a task by ID
run_task - Executes a task by ID, waits for completion, and returns the result (for on-demand tasks or ad-hoc runs of scheduled tasks)
enable_task - Enables a task so it runs on its schedule or can be triggered via run_task
disable_task - Disables a task so it stops running and cannot be triggered
get_task_result - Gets execution results for a task (latest by default, or recent history with limit)
query_task_result - Runs a read-only SQL query against the database (SELECT only, capped at 1000 rows)
Task Format
Tasks have the following structure:
{
"id": "task_a3f7b2c9e1d04f68",
"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"
}
The type field can be shell_command (default), AI, or http. The fields that apply depend on the type:
shell_command — command: the shell command to execute.
AI — prompt: what the AI should do.
http — url (required), method (defaults to POST), headers (JSON object of string→string), and body (request body string). Created via add_http_task.
For HTTP tasks, the result row reuses the existing columns:
Result field
Meaning for HTTP tasks
exit_code
HTTP status code (0 if no response was received)
output
Response body preview (capped at 8 KiB, suffixed ... (truncated))
error
Transport error, build-request error, or non-2xx status: N <reason>
duration
Round-trip latency
url
The request URL
This keeps query_task_result queries uniform — e.g. SELECT COUNT(*) FROM results WHERE task_id='x' AND exit_code >= 200 AND exit_code < 300 counts successful HTTP calls.
Scheduled vs on-demand tasks:
Scheduled: Provide a schedule (cron expression) — the task runs automatically on that schedule.
On-demand: Omit schedule — the task sits idle until triggered via run_task.
run_task also works on scheduled tasks for ad-hoc execution outside their normal schedule. After execution, scheduled tasks resume their normal schedule; on-demand tasks return to idle.
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
Cron expressions are required for scheduled tasks and omitted for on-demand tasks. The scheduler uses the github.com/robfig/cron/v3 library for parsing. 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
Building
go build -o mcp-cron cmd/mcp-cron/main.go
Testing
See docs/testing.md for the full testing guide, including integration tests and AI task tests.