MCP Scheduler

MCP Scheduler

Model Context Protocol（MCP）を使用して、さまざまな種類の自動タスクをスケジュールし、管理する堅牢なタスクスケジューラーサーバーです。

概要

MCP Scheduler は、さまざまな種類のタスクをスケジュールして実行できる、多用途のタスク自動化システムです。

• シェルコマンド：システムコマンドをスケジュールに従って実行します
• API 呼び出し：外部サービスに HTTP リクエストを送信します
• AI タスク：OpenAI モデルを使用してコンテンツを生成します
• リマインダー：サウンド付きのデスクトップ通知を表示します

スケジューラーは柔軟なタイミング設定に cron 式を使用し、タスク実行の完全な履歴を提供します。Model Context Protocol（MCP）上に構築されているため、AI アシスタントやその他の MCP 対応クライアントと簡単に統合できます。

機能

• 複数のタスクタイプ：シェルコマンド、API 呼び出し、AI コンテンツ生成、デスクトップ通知に対応
• cron スケジュール：使い慣れた cron 構文でスケジュールを正確に制御
• 1 回限りまたは繰り返し実行：タスクを 1 回だけ、またはスケジュールに従って繰り返し実行するオプション
• 実行履歴：成功したタスク実行と失敗したタスク実行を追跡
• クロスプラットフォーム：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：新しいシェルコマンドタスクを追加します
• 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 時
• 0 */2 * * * - 2 時間ごと
• 0 9-17 * * 1-5 - 月曜日から金曜日の午前 9 時から午後 5 時まで、毎時
• 0 0 1 * * - 毎月 1 日の午前 0 時
• 0 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 キー

例

シェルコマンドタスクの追加

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

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については LICENSE ファイルをご覧ください。

謝辞

• Model Context Protocol を基盤としています
• cron の解析に croniter を使用しています
• AI タスクに OpenAI API を使用しています
• MCP の機能強化に FastMCP を使用しています