MCP Scheduler

MCP Scheduler

基于 Model Context Protocol (MCP) 构建的强大任务调度服务，可用于调度和管理各种类型的自动化任务。

概述

MCP Scheduler 是一个多用途任务自动化系统，可用于调度和运行不同类型的任务：

• Shell 命令：按计划执行系统命令
• API 调用：向外部服务发送 HTTP 请求
• AI 任务：通过 OpenAI 模型生成内容
• 提醒：显示带声音的桌面通知

调度器使用 cron 表达式实现灵活的定时安排，并提供完整的任务执行历史记录。它基于 Model Context Protocol (MCP) 构建，可轻松与 AI 助手及其他兼容 MCP 的客户端集成。

功能

• 多种任务类型：支持 Shell 命令、API 调用、AI 内容生成和桌面通知
• Cron 调度：使用熟悉的 cron 语法，精确控制调度
• 单次运行或循环运行：可选择任务仅运行一次或按计划重复运行
• 执行历史：跟踪成功和失败的任务执行记录
• 跨平台：支持 Windows、macOS 和 Linux
• 交互式通知：提醒任务可发送带声音的桌面通知
• MCP 集成：与 AI 助手和工具无缝连接
• 完善的错误处理：全面的日志记录和错误恢复机制

安装

前置条件

• Python 3.10 或更高版本
• uv（推荐的包管理器）

安装 uv（推荐）

# For Mac/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# For Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安装 uv 后，重启终端以确保该命令可用。

项目设置

# Clone the repository
git clone https://github.com/phialsbasement/mcp-scheduler.git
cd mcp-scheduler

# Create and activate a virtual environment with uv
uv venv
source .venv/bin/activate  # On Unix/MacOS
# or
.venv\Scripts\activate     # On Windows

# Install dependencies with uv
uv pip install -r requirements.txt

使用标准 pip 安装（备选方式）

如果你更喜欢使用标准 pip：

# Clone the repository
git clone https://github.com/phialsbasement/mcp-scheduler.git
cd mcp-scheduler

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Unix/MacOS
# or
.venv\Scripts\activate     # On Windows

# Install dependencies
pip install -r requirements.txt

使用方法

运行服务

# Run with default settings (stdio transport)
python main.py

# Run with server transport on specific port
python main.py --transport sse --port 8080

# Run with debug mode for detailed logging
python main.py --debug

与 Claude Desktop 或其他 MCP 客户端集成

如需在 Claude Desktop 中使用 MCP Scheduler：

1. 确保已安装 Claude Desktop
2. 打开 Claude Desktop 应用配置文件：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
3. 如果文件不存在，请创建该文件，然后添加你的服务：

{
  "mcpServers": [
    {
      "type": "stdio",
      "name": "MCP Scheduler",
      "command": "python",
      "args": ["/path/to/your/mcp-scheduler/main.py"]
    }
  ]
}

如果你使用 FastMCP 库，也可以使用 fastmcp 实用工具：

# Install your server in Claude Desktop
fastmcp install main.py --name "Task Scheduler"

命令行选项

--address        Server address (default: localhost)
--port           Server port (default: 8080)
--transport      Transport mode (sse or stdio) (default: stdio)
--log-level      Logging level (default: INFO)
--log-file       Log file path (default: mcp_scheduler.log)
--db-path        SQLite database path (default: scheduler.db)
--config         Path to JSON configuration file
--ai-model       AI model to use for AI tasks (default: gpt-4o)
--version        Show version and exit
--debug          Enable debug mode with full traceback
--fix-json       Enable JSON fixing for malformed messages

配置文件

你可以使用 JSON 配置文件代替命令行参数：

{
  "server": {
    "name": "mcp-scheduler",
    "version": "0.1.0",
    "address": "localhost",
    "port": 8080,
    "transport": "sse"
  },
  "database": {
    "path": "scheduler.db"
  },
  "logging": {
    "level": "INFO",
    "file": "mcp_scheduler.log"
  },
  "scheduler": {
    "check_interval": 5,
    "execution_timeout": 300
  },
  "ai": {
    "model": "gpt-4o",
    "openai_api_key": "your-api-key"
  }
}

MCP 工具函数

MCP Scheduler 提供以下工具：

任务管理

• list_tasks：获取所有已调度的任务
• get_task：获取指定任务的详细信息
• add_command_task：添加新的 Shell 命令任务
• add_api_task：添加新的 API 调用任务
• add_ai_task：添加新的 AI 任务
• add_reminder_task：添加带桌面通知的新提醒任务
• update_task：更新现有任务
• remove_task：删除任务
• enable_task：启用已禁用的任务
• disable_task：禁用活动任务
• run_task_now：立即运行任务

执行与监控

• get_task_executions：获取任务的执行历史记录
• get_server_info：获取服务信息

Cron 表达式指南

MCP Scheduler 使用标准 cron 表达式进行调度。以下是一些示例：

• 0 0 * * * - 每天午夜
• 0 */2 * * * - 每 2 小时
• 0 9-17 * * 1-5 - 周一至周五，上午 9 点至下午 5 点之间的每个整点
• 0 0 1 * * - 每月 1 日午夜
• 0 0 * * 0 - 每周日午夜

环境变量

可以使用环境变量配置调度器：

• MCP_SCHEDULER_NAME：服务名称（默认值：mcp-scheduler）
• MCP_SCHEDULER_VERSION：服务版本（默认值：0.1.0）
• MCP_SCHEDULER_ADDRESS：服务地址（默认值：localhost）
• MCP_SCHEDULER_PORT：服务端口（默认值：8080）
• MCP_SCHEDULER_TRANSPORT：传输模式（默认值：stdio）
• MCP_SCHEDULER_LOG_LEVEL：日志级别（默认值：INFO）
• MCP_SCHEDULER_LOG_FILE：日志文件路径
• MCP_SCHEDULER_DB_PATH：数据库路径（默认值：scheduler.db）
• MCP_SCHEDULER_CHECK_INTERVAL：检查任务的频率（默认值：5 秒）
• MCP_SCHEDULER_EXECUTION_TIMEOUT：任务执行超时时间（默认值：300 秒）
• MCP_SCHEDULER_AI_MODEL：用于 AI 任务的 OpenAI 模型（默认值：gpt-4o）
• OPENAI_API_KEY：用于 OpenAI 任务的 API 密钥

示例

添加 Shell 命令任务

await scheduler.add_command_task(
    name="Backup Database",
    schedule="0 0 * * *",  # Midnight every day
    command="pg_dump -U postgres mydb > /backups/mydb_$(date +%Y%m%d).sql",
    description="Daily database backup",
    do_only_once=False  # Recurring task
)

添加 API 任务

await scheduler.add_api_task(
    name="Fetch Weather Data",
    schedule="0 */6 * * *",  # Every 6 hours
    api_url="https://api.weather.gov/stations/KJFK/observations/latest",
    api_method="GET",
    description="Get latest weather observations",
    do_only_once=False
)

添加 AI 任务

await scheduler.add_ai_task(
    name="Generate Weekly Report",
    schedule="0 9 * * 1",  # 9 AM every Monday
    prompt="Generate a summary of the previous week's sales data.",
    description="Weekly sales report generation",
    do_only_once=False
)

添加提醒任务

await scheduler.add_reminder_task(
    name="Team Meeting",
    schedule="30 9 * * 2,4",  # 9:30 AM every Tuesday and Thursday
    message="Don't forget the team standup meeting!",
    title="Meeting Reminder",
    do_only_once=False
)

MCP 自动发现端点

在 SSE（HTTP）模式下运行时，MCP Scheduler 会公开一个用于工具/架构自动发现的知名端点：

• 端点：/.well-known/mcp-schema.json（位于 HTTP 端口 + 1 上；例如，如果服务在 8080 端口运行，架构位于 8081 端口）
• **用途：**允许客户端和 AI 助手自动发现所有可用的 MCP 工具及其参数。

示例

如果运行：

python main.py --transport sse --port 8080

可以通过以下地址访问架构：

http://localhost:8081/.well-known/mcp-schema.json

示例响应

{
  "tools": [
    {
      "name": "list_tasks",
      "description": "List all scheduled tasks.",
      "endpoint": "list_tasks",
      "method": "POST",
      "parameters": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": false
      }
    },
    {
      "name": "add_command_task",
      "description": "Add a new shell command task.",
      "endpoint": "add_command_task",
      "method": "POST",
      "parameters": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "schedule": {"type": "string"},
          "command": {"type": "string"},
          "description": {"type": "string"},
          "enabled": {"type": "boolean"},
          "do_only_once": {"type": "boolean"}
        },
        "required": ["name", "schedule", "command"],
        "additionalProperties": false
      }
    }
    // ... more tools ...
  ]
}

此架构会根据已注册的 MCP 工具自动生成，并始终反映服务当前的功能。

开发

如果你想为 MCP Scheduler 做出贡献或进一步开发它，以下是一些额外的命令：

# Install the MCP SDK for development
uv pip install "mcp[cli]>=1.4.0"

# Or for FastMCP (alternative implementation)
uv pip install fastmcp

# Testing your MCP server
# With the MCP Inspector tool
mcp inspect --stdio -- python main.py

# Or with a simple MCP client
python -m mcp.client.stdio python main.py

贡献

欢迎贡献！欢迎提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

致谢

• 基于 Model Context Protocol
• 使用 croniter 解析 cron
• 使用 OpenAI API 执行 AI 任务
• 使用 FastMCP 增强 MCP 功能