Schedule Task

Schedule Task MCP is a scheduled-task management server that speaks the Model Context Protocol (MCP). It lets you create, inspect, and run jobs that trigger on intervals, cron expressions, or specific dates, while persisting state in SQLite and returning human-friendly task summaries for easy monitoring.

How to use

You interact with Schedule Task MCP through an MCP client. Start by registering the server with your client, then create and manage tasks using natural-language prompts or precise trigger configurations. Each task can run on an interval, on a cron schedule, or as a one-time date, and you can trigger runs immediately or inspect upcoming executions and history.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system.

# Install the MCP server globally
npm install -g schedule-task-mcp

# Or install from source
git clone https://github.com/liao1fan/schedule-task-mcp.git
cd schedule-task-mcp
npm install
npm run build

Additional setup and usage notes

Register the MCP server with your client to enable task management. You can run the server via a local checkout or reference the built package when you have the compiled entry point.

{
  "mcpServers": {
    "schedule-task-mcp": {
      "command": "npx",
      "args": ["-y", "schedule-task-mcp"]
    }
  }
}

If you are developing from a local checkout, point the client to the compiled entry point after building.

{
  "mcpServers": {
    "schedule-task-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/schedule-task-mcp/dist/index.js"]
    }
  }
}

Core concepts and task management

Key operations you can perform through MCP include creating, listing, inspecting, updating, deleting, pausing, resuming, and executing tasks. You can also clear a task’s run history or query the current scheduler time. The server stores tasks in SQLite at a default location and migrates any legacy data automatically.

Examples of trigger styles you can use: interval, cron, and date (one-time) triggers. You can also use delay-based shortcuts like “in 30 minutes.” For one-time dates, you can specify an explicit timestamp or a relative delay.

MCP Sampling and environment configuration

If you provide agent prompts, the scheduler can invoke MCP Sampling to execute natural-language instructions through your MCP client. You can set environment variables to customize behavior for each client, such as time zone, database path, and sampling timeouts.

Environment variables you may configure include timezone, database path, and sampling timeout. These can be set per MCP client to tailor the scheduler’s behavior to your environment.

Storage and persistence

Tasks are persisted in a SQLite database located at a default path under your home directory. Any legacy data files are migrated automatically on first run to ensure a smooth transition.

Trigger reference

Interval: define a fixed interval in seconds, minutes, hours, or days. Example: every 30 minutes.

Cron: use a five-field cron expression to schedule recurring runs, such as at 09:00 every day or at 09:00 on Mondays.

Date / Delay: for one-off tasks, provide an explicit timestamp or a relative delay (e.g., delay_minutes). If the timestamp is in the past, the server adjusts it automatically.

MCP Sampling workflow overview

When a task with an agent_prompt runs, the server can initiate a sampling flow where your MCP client receives the instruction and executes the task, then records the result in the task history.

Tips for building your own client

To enable sampling, implement a sampling_callback in your MCP client. You can use the official MCP API or an agent framework to handle the workflow and tool execution.

Roadmap highlights

Future enhancements include task dependencies, extended execution history search, web dashboard, retry policies, and webhooks for completion notifications.

Available tools

create_task

Create a new schedule with a name, trigger_type, trigger_config, and optional agent_prompt to enable MCP Sampling.

list_tasks

Display every task with status and next run.

get_task

Inspect a single task by its ID.

update_task

Modify an existing task with any field supported by create_task.

delete_task

Remove a task permanently.

pause_task

Pause a task to stop executions without deleting it.

resume_task

Resume a paused task.

execute_task

Run a task immediately as a manual trigger.

clear_task_history

Wipe the run history for a task while keeping it scheduled.

get_current_time

Return the current time in the configured timezone.