Cronicle 定时调度 MCP Server

基于官方 modelcontextprotocol/python-sdk 的 FastMCP 实现，面向 Cherry Studio、Claude Desktop、Cursor 等 MCP 客户端提供 Cronicle 定时调度系统 API 工具。

已暴露工具

工具	说明
get_schedule	获取所有定时事件列表，支持 offset/limit 分页
get_event	根据事件 ID 或标题获取单个事件详细信息
create_event	创建新的定时事件
create_one_shot_event	创建一次性任务，执行后自动禁用或删除
update_event	更新已有事件的配置
delete_event	删除指定事件
get_event_history	获取指定事件的历史完成作业记录
get_history	获取所有事件的全局历史完成作业记录
run_event	立即手动触发事件执行，不等待定时调度
get_job_status	查询作业当前状态，包括进度、资源使用等
get_active_jobs	获取当前所有正在运行的活跃作业列表
update_job	更新运行中作业的配置（超时、重试、通知等）
abort_job	强制中止一个正在运行的作业
get_master_state	获取调度器启停状态
update_master_state	启用或暂停整个调度系统

项目结构

managing-cronicle-scheduler/
├── .env.example
├── .gitignore
├── AGENTS.md
├── README.md
├── pyproject.toml
└── src/
    └── managing_cronicle_scheduler/
        ├── __init__.py
        ├── __main__.py
        ├── client.py
        └── server.py

环境要求

• Python >= 3.11
• uv 包管理器

配置

复制 .env.example 为 .env，填入 Cronicle 服务地址和 API Key：

cp .env.example .env

编辑 .env：

CRONICLE_BASE_URL=https://cron.example.com
CRONICLE_API_KEY=your-32-character-hex-api-key
CRONICLE_DEFAULT_CATEGORY=cmp6jqxkx01
CRONICLE_DEFAULT_TARGET=allgrp
CRONICLE_DEFAULT_PLUGIN=urlplug

API Key 可在 Cronicle UI 的 API Keys Tab 中创建，需 32 位十六进制字符串。

CRONICLE_DEFAULT_CATEGORY、CRONICLE_DEFAULT_TARGET、CRONICLE_DEFAULT_PLUGIN 为 create_event 工具的默认值，可在调用时覆盖。

安装依赖

uv sync

启动

默认使用 stdio 传输，这是 MCP 客户端最常用的方式：

uv run managing-cronicle-scheduler

等价方式：

uv run python -m managing_cronicle_scheduler

HTTP Transport 调试

如需 HTTP/SSE 方式启动：

uv run managing-cronicle-scheduler --transport sse --host 0.0.0.0 --port 8000
uv run managing-cronicle-scheduler --transport streamable-http --host 0.0.0.0 --port 8000

SSE 端点：/sse，Streamable HTTP 端点：/mcp。

Cherry Studio 配置示例

{
  "mcpServers": {
    "managing-cronicle": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/managing-cronicle-scheduler",
        "run",
        "managing-cronicle-scheduler"
      ],
      "env": {
        "CRONICLE_BASE_URL": "https://cron.example.com",
        "CRONICLE_API_KEY": "your-32-character-hex-api-key",
        "CRONICLE_DEFAULT_CATEGORY": "cmp6jqxkx01",
        "CRONICLE_DEFAULT_TARGET": "allgrp",
        "CRONICLE_DEFAULT_PLUGIN": "urlplug"
      }
    }
  }
}

通过 env 字段直接注入环境变量，无需 .env 文件。只有 CRONICLE_BASE_URL 和 CRONICLE_API_KEY 为必填，其余三项有默认值可省略。

如果配置界面是逐项填写：

• Command：uv
• Args：--directory /absolute/path/to/managing-cronicle-scheduler run managing-cronicle-scheduler
• Transport：stdio

OpenCode 配置

本地模式（推荐）

使用 opencode mcp add 命令添加：

opencode mcp add

按提示输入：

• 名称：managing-cronicle
• 类型：local
• 命令：uv --directory /Users/wangjun/Workspace/boscloud/managing-cronicle-scheduler run managing-cronicle-scheduler

也可以在 ~/.config/opencode/opencode.jsonc 中直接配置：

"managing-cronicle": {
  "type": "local",
  "command": [
    "uv",
    "--directory",
    "/absolute/path/to/managing-cronicle-scheduler",
    "run",
    "managing-cronicle-scheduler"
  ],
  "env": {
    "CRONICLE_BASE_URL": "https://cron.example.com",
    "CRONICLE_API_KEY": "your-32-character-hex-api-key"
  }
}

远程模式

先启动 HTTP/SSE 服务：

uv run managing-cronicle-scheduler --transport sse --host 0.0.0.0 --port 8000

再在 ~/.config/opencode/opencode.jsonc 中配置远程连接：

"managing-cronicle": {
  "type": "remote",
  "url": "http://localhost:8000/sse"
}

自测

1. 语法检查

uv run python -m compileall src

2. MCP Inspector 检查工具列表

npx @modelcontextprotocol/inspector uv --directory /absolute/path/to/managing-cronicle-scheduler run managing-cronicle-scheduler

连接成功后应能看到 15 个工具。

3. 直接启动观察

uv run managing-cronicle-scheduler --log-level DEBUG

MCP stdio 服务启动后工具列表需要由 MCP 客户端发起 tools/list 才会显示。