Schedule Task MCP

Schedule Task MCP is a scheduled-task management server that speaks the Model Context Protocol (MCP). It lets any MCP-aware agent create, inspect, and run jobs that trigger on intervals, cron expressions, or one-time dates, while persisting state in SQLite and returning rich task summaries that are easy for humans to read.

✨ Highlights

• Natural-language friendly – Designed so agents can take user phrases like “every morning at 9:30 send me an AI briefing” and turn them into actionable schedules.

• Multiple trigger styles – Interval, cron, and one-time date triggers are all supported, plus delay-based shortcuts (e.g., “in 30 minutes”).

• Rich responses – Every task operation returns a detailed Markdown summary and the raw JSON payload for downstream automation.

• SQLite persistence – Tasks live in ~/.schedule-task-mcp/tasks.db; legacy tasks.json files are migrated automatically on first run.

• Sampling-aware – When agent_prompt is provided, the scheduler can call back into the agent via MCP sampling to execute natural-language instructions.

📦 Installation

Via npm

npm install -g schedule-task-mcp

From source

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

🚀 Registering the MCP Server

Add the server to your MCP client configuration. If you rely on the npm package, npx will fetch the latest build for you:

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

When developing from a local checkout, point the client to your compiled dist/index.js:

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

You can inject environment variables directly from the MCP configuration by adding an env block. For example:

{
  "mcpServers": {
    "schedule-task-mcp": {
      "command": "npx",
      "args": ["-y", "schedule-task-mcp"],
      "env": {
        "SCHEDULE_TASK_TIMEZONE": "Asia/Shanghai",
        "SCHEDULE_TASK_DB_PATH": "~/scheduler/tasks.db",
        "SCHEDULE_TASK_SAMPLING_TIMEOUT": "300000"
      }
    }
  }
}

Any variables listed under env override the process defaults, so each MCP client can have its own scheduler settings without touching global shell configuration.

⚙️ Environment Variables

🧰 Core Tools

All tools are exposed through MCP. While arguments are shown for completeness, most agents can rely on natural-language prompts; the server will parse scheduling phrases automatically.

Every response includes:

• summary: a Markdown bullet list summarising name, ID, trigger, state, last/next execution, and agent instructions.

• detail: the raw describeTask JSON, including convenience fields such as next_run_local, last_run_local, and trigger_config_local for date triggers.

🧪 Usage Examples

• Interval – “Every 30 minutes, run ‘Check system health’.”

• Cron – “At 2 o’clock every morning, run ‘Daily backup’.”

• One-time – “Remind me about ‘Product launch meeting’ this Friday at 2 PM.”

The server fills in default names if omitted, parses the timing phrase, and stores any natural-language instruction into agent_prompt for later sampling.

🔧 Trigger Reference

Interval

Use when you need a fixed gap between runs. trigger_config accepts any combination of seconds, minutes, hours, or days:

{
  "trigger_type": "interval",
  "trigger_config": {
    "minutes": 30
  }
}

Cron

For calendar-based repetition, supply a five-field cron expression. A few handy examples:

• * * * * * – every minute

• 0 * * * * – hourly

• 0 9 * * * – every day at 09:00

• 0 9 * * 1 – Mondays at 09:00

• 0 0 1 * * – the first day of each month at midnight

Date / Delay

For one-offs, either provide an explicit ISO timestamp or relative delay fields:

{
  "trigger_type": "date",
  "trigger_config": {
    "delay_minutes": 10
  }
}

If the supplied timestamp is in the past, the server automatically adjusts it (using the delay if present, otherwise now + 1s). Date-based tasks mark themselves complete once they run.

🗄️ Storage

• Default database: ~/.schedule-task-mcp/tasks.db

• A legacy tasks.json in the same folder is migrated to SQLite the first time the new server runs (backup saved as tasks.json.bak).

🔌 Integration Notes

You can still attach mcp_server, mcp_tool, and mcp_arguments to a task for future MCP-to-MCP orchestration. At present the scheduler doesn't call other servers directly; instead, prefer agent_prompt so the agent can coordinate follow-up actions through sampling.

🔄 MCP Sampling Support

Schedule Task MCP supports MCP Sampling, which allows the server to call back into the MCP client when a scheduled task triggers. This enables powerful automation workflows where your AI agent can be automatically invoked to execute tasks.

How It Works

When you create a task with an agent_prompt, the scheduler will:

1. Trigger at scheduled time – The task runs based on its trigger configuration (interval, cron, or date)

2. Send sampling request – The server sends a sampling/createMessage request to the MCP client

3. Execute agent logic – Your client's sampling_callback receives the agent_prompt and executes the task

4. Record results – The execution result is recorded in the task history

Example Workflow

User: "Every day at 9am, check for new videos and send me a summary"
  ↓
Agent creates task with:
  - trigger: cron "0 9 * * *"
  - agent_prompt: "check for new videos and send me a summary"
  ↓
Next day at 9am:
  - schedule-task-mcp sends sampling request
  - Client receives agent_prompt
  - Agent executes: checks videos → generates summary → sends email
  - Result recorded in task history

Creating a Sampling-Enabled Client

To use MCP Sampling with schedule-task-mcp, you need to implement a sampling_callback in your MCP client. We provide two approaches:

1. Using MCP Official API (Python) – Simple, direct implementation for straightforward tasks

2. Using OpenAI Agents SDK (Python) – Powerful agent-based implementation with automatic tool calling

📖 For detailed implementation guides, code examples, and best practices, see

The guide includes:

• Complete code examples for both approaches

• Step-by-step setup instructions

• Comparison of the two methods

• Troubleshooting tips

• Reference to working implementations

🛣️ Roadmap

• Task dependencies

• Extended execution history and search

• Webhooks / notifications on completion

• Retry policies

• Web dashboard for interactive management

🤝 Contributing

PRs are welcome! Please file an issue or open a pull request with improvements or bug fixes.

📄 License

MIT License

🙏 Acknowledgements

• Model Context Protocol – specification and reference ecosystem

• node-cron – cron implementation used under the hood

• APScheduler – inspiration for the scheduling model