# Schedule Task MCP
[](https://www.npmjs.com/package/schedule-task-mcp)
[](https://opensource.org/licenses/MIT)
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
```bash
npm install -g schedule-task-mcp
```
### From source
```bash
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:
```json
{
"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`:
```json
{
"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:
```json
{
"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
| Variable | Description |
| --- | --- |
| `SCHEDULE_TASK_DB_PATH` | Override the SQLite location (default `~/.schedule-task-mcp/tasks.db`). A legacy `tasks.json` found in the same folder is migrated once. |
| `SCHEDULE_TASK_TIMEZONE` | Force a timezone when formatting `*_local` timestamps; defaults to the host timezone. |
| `SCHEDULE_TASK_SAMPLING_TIMEOUT` | Timeout in milliseconds for `sampling/createMessage` calls (default `180000`, i.e., 3 minutes). |
## 🧰 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.
| Tool | Purpose | Typical natural-language prompt |
| --- | --- | --- |
| `create_task` | Create a new schedule. Accepts `name`, `trigger_type`, `trigger_config`, and optional `agent_prompt`. | “Every weekday at 9am, check for new videos and email me the AI briefing.” |
| `list_tasks` | Display every task with status and next run. | “Show me all my scheduled jobs.” |
| `get_task` | Inspect a single task by ID. | “Give me the details for task-123.” |
| `update_task` | Modify an existing task (any field supported by `create_task`). | “Change task-123 so it runs every 2 hours instead.” |
| `delete_task` | Remove a task permanently. | “Delete task-123.” |
| `pause_task` / `resume_task` | Toggle execution without deleting. | “Pause task-123.” / “Resume task-123.” |
| `execute_task` | Run immediately (manual trigger). | “Run task-123 right now.” |
| `clear_task_history` | Wipe stored history for a task while keeping it scheduled. | “Clear the run history for task-123.” |
| `get_current_time` | Return the current time in the configured timezone. | “What time is it for the scheduler?” |
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`:
```json
{
"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:
```json
{
"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 [MCP_SAMPLING_GUIDE.md](./MCP_SAMPLING_GUIDE.md)**
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](LICENSE)
## 🙏 Acknowledgements
- [Model Context Protocol](https://modelcontextprotocol.io/) – specification and reference ecosystem
- [node-cron](https://github.com/node-cron/node-cron) – cron implementation used under the hood
- [APScheduler](https://apscheduler.readthedocs.io/) – inspiration for the scheduling model
