MCP Cron

MCP Cron

Model Context Protocol (MCP) サーバーで、標準化された API を通じてタスクのスケジュール設定と管理を行います。このサーバーは、シェルコマンドと AI を活用したタスクの両方をサポートするタスクスケジューリング機能を提供し、すべて MCP プロトコル経由でアクセスできます。

機能

• cron 式を使用してシェルコマンドまたは 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)。カスタムベース URL が設定されている場合、mcp-cron は自動的に Responses API の代わりに Chat Completions 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

使用方法

サーバーは 2 つのトランスポートモードをサポートしています:

• 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 トランスポートは、以下の場合に特に便利です:

• 他のプロセスへの/からの直接パイピング
• CLI ツールとの統合
• 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 互換エンドポイント用のカスタムベース 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 互換エンドポイント (Ollama、vLLM、Groq、LiteLLM など) 用のカスタムベース URL	未設定
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 タスクに使用する LLM モデル	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 トランスポートで実行する場合、JSON-RPC プロトコルへの干渉を防ぐため、ログは mcp-cron.log ログファイルにリダイレクトされます:

• ログファイルの場所: mcp-cron バイナリと同じ場所。
• タスクの出力、実行の詳細、サーバーの診断情報はこのファイルに書き込まれます。
• stdout/stderr ストリームはプロトコルメッセージ専用としてクリーンな状態に保たれます。

利用可能な MCP ツール

このサーバーは、MCP プロトコルを通じていくつかのツールを公開しています：

1. list_tasks - すべてのタスク（スケジュール実行とオンデマンド）を一覧表示します
2. get_task - ID を指定して特定のタスクを取得します
3. add_task - 新しいシェルコマンドタスクを追加します（繰り返し実行には schedule を指定し、オンデマンドの場合は省略します）
4. add_ai_task - プロンプトを指定して新しい AI（LLM）タスクを追加します（繰り返し実行には 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 を指定できます。適用されるフィールドは type によって異なります：

• shell_command — command: 実行するシェルコマンド。
• AI — prompt: AI が実行すべき内容。
• http — url（必須）、method（デフォルトは POST）、headers（string→string の 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 0 12 * * MON-FRI - 平日の正午に

開発

ビルド

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

テスト

統合テストや AI タスクのテストを含む完全なテストガイドについては、docs/testing.md を参照してください。

謝辞

• modelcontextprotocol/go-sdk - Model Context Protocol の公式 Go SDK
• robfig/cron - Go 向けの Cron 式解析