Q Scheduler MCP

🚀 MCP Scheduler

MCP Schedulerは、Model Context Protocol (MCP) を用いて構築された堅牢なタスクスケジューラサーバーです。様々な自動化タスクのスケジューリングと管理を行うことができます。

このリポジトリは、https://github.com/PhialsBasement/scheduler-mcp からフォークされたものです。

🚀 クイックスタート

MCP Schedulerは、様々なタイプのタスクをスケジューリングして実行できる汎用的なタスク自動化システムです。以下のようなタスクをサポートしています。

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

このスケジューラは、柔軟なタイミング設定のためにcron式を使用し、タスクの実行履歴を完全に記録します。Model Context Protocol (MCP) をベースに構築されているため、AIアシスタントや他のMCP互換クライアントとの統合が容易です。

✨ 主な機能

• 複数のタスクタイプ：シェルコマンド、API呼び出し、AIコンテンツ生成、デスクトップ通知をサポートしています。
• Cronスケジューリング：正確なスケジューリング制御のために、一般的なcron構文を使用します。
• 一度だけ実行または定期実行：タスクを一度だけ実行するか、スケジュールに基づいて繰り返し実行することができます。
• 実行履歴：タスクの成功と失敗の実行履歴を追跡します。
• クロスプラットフォーム：Windows、macOS、Linuxで動作します。
• インタラクティブな通知：リマインダータスクに音声付きのデスクトップアラートを使用します。
• MCP統合：AIアシスタントやツールとのシームレスな接続が可能です。
• 堅牢なエラーハンドリング：包括的なロギングとエラー回復機能を備えています。

📦 インストール

前提条件

• Python 3.10以上
• uv（推奨のパッケージマネージャー）

uvのインストール（推奨）

# Mac/Linuxの場合
curl -LsSf https://astral.sh/uv/install.sh | sh

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

uvをインストールした後、コマンドが使用可能になるようにターミナルを再起動してください。

uvを使用したプロジェクトのセットアップ（推奨）

# リポジトリをクローンする
git clone https://github.com/yourusername/mcp-scheduler.git
cd mcp-scheduler

# uvで仮想環境を作成してアクティブ化する
uv venv
source .venv/bin/activate  # Unix/MacOSの場合
# または
.venv\Scripts\activate     # Windowsの場合

# uvで依存関係をインストールする
uv pip install -r requirements.txt

標準のpipを使用したインストール（代替方法）

標準のpipを使用する場合は、以下の手順を実行してください。

# リポジトリをクローンする
git clone https://github.com/yourusername/mcp-scheduler.git
cd mcp-scheduler

# 仮想環境を作成してアクティブ化する
python -m venv .venv
source .venv/bin/activate  # Unix/MacOSの場合
# または
.venv\Scripts\activate     # Windowsの場合

# 依存関係をインストールする
pip install -r requirements.txt

💻 使用例

サーバーの起動

# まず仮想環境をアクティブ化する
source .venv/bin/activate  # Unix/MacOSの場合
# または
.venv\Scripts\activate     # Windowsの場合

# デフォルト設定で起動する（stdioトランスポート）
uv run main.py

# AWS Qとの統合で起動する（Amazon Qユーザーに推奨）
uv run start_with_aws_q.py

# 詳細なログを出力するデバッグモードで起動する
uv run main.py --debug

# カスタム設定ファイルを使用して起動する
uv run main.py --config /path/to/config.json

サーバーはデフォルトでstdioトランスポートを使用します。これは、Amazon Qや他のMCPクライアントとの統合に最適です。サーバーは環境に基づいて通信プロトコルを自動的に処理します。

Amazon Q、Claude Desktopまたは他のMCPクライアントとの統合

Amazon Qとの統合

MCP SchedulerをAmazon Qと共に使用するには、以下の手順を実行してください。

1. Amazon Q CLIがインストールされていることを確認します。
2. AWS Qモデルパッチでスケジューラを起動します。

# AWS Qとの統合でスケジューラを起動する
uv run start_with_aws_q.py

これにより、スケジューラが自動的にAmazon Qに登録され、自然言語コマンドを使用してタスクを作成および管理できるようになります。

例のコマンド：

• "Create a scheduled task to backup my config file every night at 10:30 PM"
• "Show me all my scheduled tasks"
• "Run the backup task now"

Amazon Qを使用したより多くの使用例については、examplesディレクトリを参照してください。

Claude Desktopとの統合

MCP SchedulerをClaude Desktopと共に使用するには、以下の手順を実行してください。

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ユーティリティを使用することができます。

# Claude Desktopにサーバーをインストールする
fastmcp install main.py --name "Task Scheduler"

コマンドラインオプション

--address        サーバーアドレス（デフォルト: localhost）
--port           サーバーポート（デフォルト: 8080）
--transport      トランスポートモード（stdioまたはsse）（デフォルト: stdio）
--log-level      ログレベル（デフォルト: INFO）
--log-file       ログファイルのパス（デフォルト: mcp_scheduler.log）
--db-path        SQLiteデータベースのパス（デフォルト: scheduler.db）
--config         JSON設定ファイルのパス
--ai-model       AIタスクに使用するAIモデル（デフォルト: gpt-4o）
--version        バージョンを表示して終了する
--debug          完全なトレースバックを表示するデバッグモードを有効にする
--fix-json       不正なJSONメッセージを修正する機能を有効にする

Amazon Qと共に使用する場合、これらのオプションの多くはstart_with_aws_q.pyスクリプトによって自動的に構成されます。

設定ファイル

コマンドライン引数の代わりにJSON設定ファイルを使用することができます。

{
  "server": {
    "name": "mcp-scheduler",
    "version": "0.1.0",
    "address": "localhost",
    "port": 8080,
    "transport": "stdio"
  },
  "database": {
    "path": "scheduler.db"
  },
  "logging": {
    "level": "INFO",
    "file": "mcp_scheduler.log"
  },
  "scheduler": {
    "check_interval": 5,
    "execution_timeout": 300
  },
  "ai": {
    "model": "gpt-4o",
    "use_aws_q_model": true,
    "openai_api_key": "your-api-key"  // AWS Qモデルを使用しない場合のみ必要
  }
}

Amazon Qと共に使用する場合、use_aws_q_modelをtrueに設定し、APIキーは不要です。

重要な注意事項

タスクタイプと制限

MCP Schedulerはアプリケーションレベルのタスクスケジューラサーバーであり、システムレベルの定時タスクマネージャーではありません。

• アプリケーションレベルのタスク：MCP Schedulerで作成されたタスクは、それ自身のデータベースに保存され、MCP Schedulerサービスが実行されているときのみ実行されます。
• 非システムレベル：これらのタスクはシステムのcrontabやsystemdタイマーではなく、システム起動時に自動的に実行されません。
• サービス依存：MCP Schedulerサービスが停止した場合、タスクは実行されません。
• ユーザー権限：タスクはMCP Schedulerを実行しているユーザーの権限で実行され、root権限ではありません。

システムレベルの定時タスク（システム起動時に自動的に実行されるか、root権限が必要な場合）が必要な場合は、以下の方法を検討してください。

1. オペレーティングシステムのcrontab -eまたはsystemctlを使用して直接システムレベルの定時タスクを作成する。
2. システムレベルの定時タスクを管理するスクリプトを実行するMCP Schedulerタスクを作成する。

永続化とサービス管理

MCP Schedulerがシステム再起動後も継続して実行されるようにするには、以下の方法を使用できます。

1. システムサービスとして設定する（systemdを使用）
2. ユーザーログイン時に自動的に起動するように設定する
3. クラウド環境でコンテナまたはサービスとして実行する

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時から17時まで毎時
• 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またはsse）（デフォルト: stdio）
• MCP_SCHEDULER_LOG_LEVEL: ログレベル（デフォルト: INFO）
• MCP_SCHEDULER_LOG_FILE: ログファイルのパス
• MCP_SCHEDULER_DB_PATH: SQLiteデータベースのパス（デフォルト: scheduler.db）
• MCP_SCHEDULER_CHECK_INTERVAL: タスクをチェックする頻度（デフォルト: 5秒）
• MCP_SCHEDULER_EXECUTION_TIMEOUT: タスクの実行タイムアウト（デフォルト: 300秒）
• MCP_SCHEDULER_AI_MODEL: AIタスクに使用するAIモデル（デフォルト: gpt-4o）
• MCP_SCHEDULER_USE_AWS_Q_MODEL: AIタスクにAWS Qモデルを使用するかどうか（デフォルト: false）
• OPENAI_API_KEY: OpenAIタスクのAPIキー（AWS Qモデルを使用しない場合のみ必要）

使用例

MCP Schedulerは、Amazon QなどのMCPクライアントを介した自然言語インタラクションまたはプログラミングAPIを通じて使用することができます。

Amazon Qを使用した場合

Amazon Qを使用してタスクを作成および管理するのは非常に簡単です。自然言語で希望するタスクを記述するだけです。

1. コマンドタスクの作成：

   毎晩10:30にデータベースを/backupsディレクトリにバックアップする定時タスクを作成してください。
   

2. API呼び出しタスクの作成：

   6時間ごとに天気データを取得するタスクを設定してください。
   

3. AIタスクの作成：

   毎週月曜日の午前9時に前週の販売データの要約レポートを生成してください。
   

4. リマインダータスクの作成：

   毎週火曜日と木曜日の午前9:30にチーム会議に参加することを通知してください。
   

5. すべてのタスクの表示：

   すべての定時タスクを表示してください。
   

6. タスクの即時実行：

   バックアップタスクをすぐに実行してください。
   

プログラミングAPIを使用した場合

アプリケーションやスクリプトを開発している場合は、プログラミング方式でMCP Schedulerとやり取りすることができます。以下は呼び出し関係を確立する簡単なガイドです。

1. 必要な依存関係のインストール

# uvを使用してインストールする（推奨）
uv pip install "mcp[client]>=1.4.0"

2. 接続を確立してAPIを呼び出す

import asyncio
from mcp.client import StdioClient

async def main():
    # MCP Schedulerを子プロセスとして起動する
    process_args = ["uv", "run", "/path/to/scheduler-mcp/main.py"]
    async with StdioClient.create_subprocess(process_args) as client:
        # サーバー情報を取得する
        server_info = await client.call("get_server_info")
        print(f"{server_info['name']} バージョン {server_info['version']} に接続しました。")
        
        # すべてのタスクをリストする
        tasks = await client.call("list_tasks")
        print(f"現在 {len(tasks)} 個のタスクがあります。")
        
        # コマンドタスクを追加する
        cmd_task = await client.call(
            "add_command_task", 
            {
                "name": "システム状態チェック",
                "schedule": "*/30 * * * *",  # 30分ごと
                "command": "vmstat > /tmp/vmstat_$(date +%Y%m%d_%H%M).log",
                "description": "システム状態を記録する",
                "do_only_once": False
            }
        )
        print(f"コマンドタスクを作成しました: {cmd_task['id']}")
        
        # タスクをすぐに実行する
        run_result = await client.call(
            "run_task_now", 
            {"task_id": cmd_task['id']}
        )
        print(f"タスクの実行結果: {run_result['execution']['status']}")

# メイン関数を実行する
if __name__ == "__main__":
    asyncio.run(main())

3. 実行中のMCP Schedulerに接続する

MCP SchedulerがHTTPモードで実行されている場合、SSEクライアントを使用して接続することができます。

import asyncio
from mcp.client import SseClient

async def connect_to_running_scheduler():
    async with SseClient("http://localhost:8080") as client:
        tasks = await client.call("list_tasks")
        print(f"現在 {len(tasks)} 個のタスクがあります。")

asyncio.run(connect_to_running_scheduler())

4. エラーハンドリング

import asyncio
from mcp.client import StdioClient
from mcp.errors import McpError

async def robust_scheduler_client():
    try:
        process_args = ["uv", "run", "/path/to/scheduler-mcp/main.py"]
        async with StdioClient.create_subprocess(process_args) as client:
            try:
                result = await client.call("list_tasks")
                return result
            except McpError as e:
                print(f"MCP APIエラー: {e}")
                return []
    except Exception as e:
        print(f"接続エラー: {e}")
        return []

asyncio.run(robust_scheduler_client())

完全な使用例

完全なAPI使用例（MCP Schedulerサービスへの接続、タスクの作成、実行、更新および削除、タスク実行履歴の取得、エラーハンドリングおよび例外管理を含む）については、examples/api_client_example.pyを参照してください。

# サンプルを実行する
cd examples
./api_client_example.py

サンプルスクリプト

examplesディレクトリには、一般的なユースケースに適した、すぐに使用できるスクリプトと設定が含まれています。

• backup_mcp_config.sh：Amazon Q MCP設定ファイルをバックアップするスクリプトで、日付に基づく命名と保持ポリシーが含まれています。

MCPツールの検出

MCP Schedulerは、Model Context Protocolを通じた自動ツール検出をサポートしています。

Stdioモード（デフォルト）

Stdioモード（デフォルト）で実行する場合、ツールの検出はMCPプロトコルを通じて自動的に行われます。これは、Amazon Qやstdio通信をサポートする他のMCPクライアントとの使用に推奨されるモードです。

# Stdioモードで実行する（デフォルト）
uv run main.py

HTTPモード（オプション）

サーバーをHTTPモードで実行する必要がある場合は、SSEトランスポートを使用し、よく知られたエンドポイントを通じてスキーマにアクセスすることができます。

# HTTPサーバートランスポートで実行する
uv run main.py --transport sse --port 8080

HTTPモードでは、サーバーはツール/スキーマの自動検出のためのよく知られたエンドポイントを公開します。

• エンドポイント：/.well-known/mcp-schema.json（HTTPポート + 1、例えばサーバーが8080で実行されている場合、スキーマは8081で利用可能）
• 目的：クライアントやAIアシスタントがすべての利用可能なMCPツールとそのパラメータを自動的に検出できるようにします。

スキーマには以下のURLからアクセスできます。

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
      }
    }
    // ... 他のツール ...
  ]
}

このスキーマは、登録されたMCPツールから自動的に生成され、常に現在のサーバーの機能を反映しています。

開発

MCP Schedulerに貢献したり、さらに開発したい場合は、以下の追加コマンドが役立ちます。

# 開発用にMCP SDKをインストールする
uv pip install "mcp[cli]>=1.4.0"

# またはFastMCP（代替実装）の場合
uv pip install fastmcp

# MCPサーバーのテスト
# MCPインスペクターツールを使用する
mcp inspect --stdio -- uv run main.py

# または簡単なMCPクライアントを使用する
python -m mcp.client.stdio uv run main.py

# テストの実行
uv run -m pytest

# コードの静的解析
uv pip install flake8
flake8 mcp_scheduler/

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細については、LICENSEファイルを参照してください。