MCP Cron

MCP Cron

Model Context Protocol (MCP) 服务，用于通过标准化 API 调度和管理任务。该服务提供任务调度能力，支持 shell 命令和 AI 驱动的任务，均可通过 MCP 协议访问。

功能特性

• 使用 cron 表达式调度 shell 命令或向 AI 发送提示词任务
• AI 可以访问 MCP 服务
• 通过 MCP 协议管理任务
• 任务执行并捕获命令输出
• 任务在重启后持久化（SQLite）
• 多实例安全 — 多个实例可共享同一数据库而不会重复执行
• 通过不同的 --db-path 支持多个隔离实例

安装

npm（推荐）

npx -y mcp-cron

Claude Code

claude mcp add mcp-cron -- npx -y mcp-cron

Cursor / Claude Desktop

{
  "mcpServers": {
    "mcp-cron": {
      "command": "npx",
      "args": ["-y", "mcp-cron", "--transport", "stdio"]
    }
  }
}

推荐配置

更完整的设置，包含 AI 提供商、模型选择和防止休眠：

{
  "mcpServers": {
    "mcp-cron": {
      "command": "npx",
      "args": [
        "-y", "mcp-cron",
        "--transport", "stdio",
        "--prevent-sleep",
        "--ai-provider", "anthropic",
        "--ai-model", "claude-sonnet-4-5-20250929"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key"
      }
    }
  }
}

使用 LiteLLM

通过 LiteLLM 代理路由 AI 任务：

{
  "mcpServers": {
    "mcp-cron": {
      "command": "npx",
      "args": [
        "-y", "mcp-cron",
        "--transport", "stdio",
        "--prevent-sleep",
        "--ai-base-url", "https://litellm.yourcompany.com",
        "--ai-model", "claude-sonnet-4-5-20250929"
      ],
      "env": {
        "MCP_CRON_AI_API_KEY": "sk-your-litellm-key"
      }
    }
  }
}

--ai-model 的值应与你的 LiteLLM 代理配置中的模型名称一致。LiteLLM 暴露的是与 OpenAI 兼容的 API，因此可以省略 --ai-provider（默认为 openai）。当设置了自定义 base URL 时，mcp-cron 会自动使用 Chat Completions API 而非 Responses API。Responses API 仅用于直连 OpenAI（api.openai.com）和 Azure OpenAI（*.openai.azure.com）端点。

所有可用选项请参见命令行参数和环境变量。

从源码构建

前置条件

• Go 1.24.0 或更高版本

# 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

使用方法

该服务支持两种传输模式：

• HTTP (Streamable HTTP)：面向浏览器和网络客户端的默认基于 HTTP 的传输
• stdio：标准输入/输出传输，用于直接管道和进程间通信

客户端	配置文件位置
Cursor	~/.cursor/mcp.json
Claude Desktop (Mac)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json

HTTP (Streamable HTTP)

# 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

配置文件示例

{
  "mcpServers": {
    "mcp-cron": {
      "url": "http://localhost:8080"
    }
  }
}

stdio

stdio 传输特别适用于：

• 与其他进程之间直接管道传输
• 与命令行工具集成
• 在无 HTTP 的环境中测试
• Docker 容器集成

启动 Cursor IDE 和 Claude Desktop 后，它将自动启动该服务

配置文件示例

{
  "mcpServers": {
    "mcp-cron": {
      "command": "<path to where mcp-cron binary is located>/mcp-cron",
      "args": ["--transport", "stdio"]
    }
  }
}

命令行参数

支持以下命令行参数：

参数	描述	默认值
--address	服务绑定的地址	localhost
--port	服务绑定的端口	8080
--transport	传输模式：http 或 stdio	http
--log-level	日志级别：debug、info、warn、error、fatal	info
--log-file	日志文件路径	stdout
--version	显示版本信息并退出	false
--ai-provider	AI 提供商：openai 或 anthropic	openai
--ai-base-url	用于 OpenAI 兼容端点的自定义 base URL（例如 Ollama、vLLM、Groq、LiteLLM）	未设置
--ai-model	用于 AI 任务的 AI 模型	gpt-4o
--ai-max-iterations	启用工具的 AI 任务的最大迭代次数	20
--mcp-config-path	MCP 配置文件路径	~/.cursor/mcp.json
--db-path	用于结果历史的 SQLite 数据库路径	~/.mcp-cron/results.db
--prevent-sleep	在 mcp-cron 运行期间防止系统休眠（macOS 和 Windows）	false
--poll-interval	检查到期任务的频率	1s

环境变量

支持以下环境变量：

环境变量	描述	默认值
MCP_CRON_SERVER_ADDRESS	服务绑定的地址	localhost
MCP_CRON_SERVER_PORT	服务绑定的端口	8080
MCP_CRON_SERVER_TRANSPORT	传输模式：http 或 stdio	http
MCP_CRON_SERVER_NAME	已弃用 — 被忽略；服务名称固定，以确保自引用检测正常工作	-
MCP_CRON_SERVER_VERSION	已弃用 — 被忽略；版本在构建时通过 ldflags 设置	-
MCP_CRON_SCHEDULER_DEFAULT_TIMEOUT	任务执行的默认超时时间	10m
MCP_CRON_LOGGING_LEVEL	日志级别：debug、info、warn、error、fatal	info
MCP_CRON_LOGGING_FILE	日志文件路径	stdout
MCP_CRON_AI_PROVIDER	AI 提供商：openai 或 anthropic	openai
MCP_CRON_AI_BASE_URL	用于 OpenAI 兼容端点的自定义 base URL（例如 Ollama、vLLM、Groq、LiteLLM）	未设置
MCP_CRON_AI_API_KEY	通用备用 API 密钥（在未设置提供商专属密钥时使用）	未设置
OPENAI_API_KEY	用于 AI 任务的 OpenAI API 密钥	未设置
ANTHROPIC_API_KEY	用于 AI 任务的 Anthropic API 密钥	未设置
MCP_CRON_ENABLE_OPENAI_TESTS	启用 OpenAI 集成测试	false
MCP_CRON_AI_MODEL	用于 AI 任务的大模型	gpt-4o
MCP_CRON_AI_MAX_TOOL_ITERATIONS	启用工具的任务的最大迭代次数	20
MCP_CRON_MCP_CONFIG_FILE_PATH	MCP 配置文件的路径	~/.cursor/mcp.json
MCP_CRON_STORE_DB_PATH	用于结果历史的 SQLite 数据库路径	~/.mcp-cron/results.db
MCP_CRON_PREVENT_SLEEP	在 mcp-cron 运行时阻止系统休眠（macOS 和 Windows）	false
MCP_CRON_POLL_INTERVAL	检查到期任务的频率（Go duration 格式）	1s

阻止休眠

在笔记本电脑上，系统可能会进入休眠状态，导致计划任务无法按时运行。使用 --prevent-sleep 标志可在 mcp-cron 运行时保持系统唤醒：

mcp-cron --prevent-sleep --transport stdio

或通过环境变量：

MCP_CRON_PREVENT_SLEEP=true mcp-cron --transport stdio

平台	机制	备注
macOS	caffeinate	阻止空闲休眠；退出时自动清理
Windows	SetThreadExecutionState	阻止空闲休眠；退出时自动清理
Linux	不支持	Linux 服务器通常不会自动休眠

注意： 这仅阻止空闲休眠。它不会阻止因合上笔记本电脑盖子或按下电源按钮而导致的休眠。

日志

使用默认 HTTP 传输运行时，日志会输出到控制台。

使用 stdio 传输运行时，日志会重定向到 mcp-cron.log 日志文件，以防止干扰 JSON-RPC 协议：

• 日志文件位置：与 mcp-cron 二进制文件相同的位置。
• 任务输出、执行详情和服务诊断信息会写入此文件。
• stdout/stderr 流保持干净，仅用于协议消息。

可用的 MCP 工具

该服务通过 MCP 协议公开了多个工具：

1. list_tasks - 列出所有任务（定时任务和按需任务）
2. get_task - 根据 ID 获取特定任务
3. add_task - 添加新的 shell 命令任务（提供 schedule 表示定时任务，省略则为按需任务）
4. add_ai_task - 添加带有提示词的新 AI（大模型）任务（提供 schedule 表示定时任务，省略则为按需任务）
5. add_http_task - 添加向 url 发起 HTTP 请求的新 HTTP（webhook）任务（提供 schedule 表示定时任务，省略则为按需任务）
6. update_task - 更新现有任务
7. remove_task - 根据 ID 移除任务
8. run_task - 根据 ID 执行任务，等待完成并返回结果（适用于按需任务或对定时任务的临时运行）
9. enable_task - 启用任务，使其按计划运行或可通过 run_task 触发
10. disable_task - 禁用任务，使其停止运行且无法被触发
11. get_task_result - 获取任务的执行结果（默认最新，或通过 limit 获取近期历史记录）
12. query_task_result - 对数据库执行只读 SQL 查询（仅限 SELECT，最多 1000 行）

任务格式

任务具有以下结构：

{
  "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"
}

type 字段可以是 shell_command（默认）、AI 或 http。适用的字段取决于类型：

• shell_command — command：要执行的 shell 命令。
• AI — prompt：AI 应该做什么。
• http — url（必需）、method（默认为 POST）、headers（字符串→字符串的 JSON 对象）和 body（请求体字符串）。通过 add_http_task 创建。

对于 HTTP 任务，结果行复用现有列：

结果字段	HTTP 任务的含义
exit_code	HTTP 状态码（如果未收到响应则为 0）
output	响应体预览（上限 8 KiB，后缀为 ... (truncated)）
error	传输错误、构建请求错误，或 non-2xx status: N <reason>
duration	往返延迟
url	请求 URL

这使 query_task_result 查询保持统一——例如 SELECT COUNT(*) FROM results WHERE task_id='x' AND exit_code >= 200 AND exit_code < 300 统计成功的 HTTP 调用。

定时任务与按需任务：

• 定时：提供 schedule（cron 表达式）——任务按该计划自动运行。
• 按需：省略 schedule——任务保持空闲，直到通过 run_task 触发。

run_task 也可用于定时任务，以在其正常计划之外临时执行。执行后，定时任务恢复正常计划；按需任务返回空闲状态。

任务状态

任务可以具有以下状态值：

• pending - 任务尚未运行
• running - 任务当前正在运行
• completed - 任务已成功完成
• failed - 任务在执行期间失败
• disabled - 任务已禁用，不会按计划运行

Cron 表达式格式

定时任务需要 cron 表达式，按需任务则省略。调度器使用 github.com/robfig/cron/v3 库进行解析。格式包含秒：

┌───────────── 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)
│ │ │ │ │ │
│ │ │ │ │ │
* * * * * *

示例：

• 0 */5 * * * * - 每 5 分钟（在第 0 秒）
• 0 0 * * * * - 每小时
• 0 0 0 * * * - 每天午夜
• 0 0 12 * * MON-FRI - 每个工作日的正午

开发

构建

go build -o mcp-cron cmd/mcp-cron/main.go

测试

参见 docs/testing.md 获取完整测试指南，包括集成测试和 AI 任务测试。

致谢

• modelcontextprotocol/go-sdk - Model Context Protocol 的官方 Go SDK
• robfig/cron - Go 的 Cron 表达式解析