Q Scheduler MCP

🚀 MCP Scheduler

MCP Scheduler is a robust task scheduler server built with the Model Context Protocol (MCP). It enables you to schedule and manage various types of automated tasks, offering a flexible and efficient solution for task automation.

Fork from https://github.com/PhialsBasement/scheduler-mcp

🚀 Quick Start

MCP Scheduler is a versatile task automation system. To get started, you need to complete the installation first. After that, you can schedule different types of tasks, such as shell commands, API calls, AI tasks, and reminders. You can use cron expressions for flexible timing and view the execution history of tasks.

✨ Features

• Multiple Task Types: Support for shell commands, API calls, AI content generation, and desktop notifications.
• Cron Scheduling: Utilize the familiar cron syntax for precise scheduling control.
• Run Once or Recurring: Option to run tasks just once or repeatedly on schedule.
• Execution History: Track successful and failed task executions.
• Cross-Platform: Works on Windows, macOS, and Linux.
• Interactive Notifications: Desktop alerts with sound for reminder tasks.
• MCP Integration: Seamless connection with AI assistants and tools.
• Robust Error Handling: Comprehensive logging and error recovery.

📦 Installation

Prerequisites

• Python 3.10 or higher
• uv (recommended package manager)

Installing uv (recommended)

# 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"

After installing uv, restart your terminal to ensure the command is available.

Project Setup with uv (recommended)

# Clone the repository
git clone https://github.com/yourusername/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

Standard pip installation (alternative)

If you prefer using standard pip:

# Clone the repository
git clone https://github.com/yourusername/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

💻 Usage Examples

Basic Usage

Running the Server

# Activate the virtual environment first
source .venv/bin/activate  # On Unix/MacOS
# or
.venv\Scripts\activate     # On Windows

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

# Run with AWS Q integration (recommended for Amazon Q users)
uv run start_with_aws_q.py

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

# Run with custom configuration file
uv run main.py --config /path/to/config.json

The server uses stdio transport by default, which is ideal for integration with Amazon Q and other MCP clients. The server automatically handles the communication protocol based on the environment.

Advanced Usage

Integrating with Amazon Q, Claude Desktop or other MCP Clients

Amazon Q Integration

To use MCP Scheduler with Amazon Q:

1. Make sure you have Amazon Q CLI installed.
2. Run the scheduler with the AWS Q model patch:

# Start the scheduler with AWS Q integration
uv run start_with_aws_q.py

This will automatically register the scheduler with Amazon Q, allowing you to create and manage tasks through natural language commands.

Example commands:

• "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"

See the examples directory for more usage examples with Amazon Q.

Claude Desktop Integration

To use your MCP Scheduler with Claude Desktop:

1. Make sure you have Claude Desktop installed.
2. Open your Claude Desktop App configuration at:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Create the file if it doesn't exist, and add your server:

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

Alternatively, use the fastmcp utility if you're using the FastMCP library:

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

Command Line Options

--address        Server address (default: localhost)
--port           Server port (default: 8080)
--transport      Transport mode (stdio or sse) (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

When using with Amazon Q, most of these options are automatically configured by the start_with_aws_q.py script.

Configuration File

You can use a JSON configuration file instead of command-line arguments:

{
  "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"  // Only needed if not using AWS Q model
  }
}

When using with Amazon Q, the use_aws_q_model should be set to true and no API key is required.

Important Notes

Task Types and Limitations

MCP Scheduler is an application-level task scheduling service, not a system-level task manager:

• Application-Level Tasks: Tasks created by MCP Scheduler are stored in its own database and are only executed when the MCP Scheduler service is running.
• Non-System-Level: These tasks are not system crontab or systemd timers and will not run automatically at system startup.
• Service Dependency: If the MCP Scheduler service stops, tasks will not be executed.
• User Permissions: Tasks are executed with the permissions of the user running MCP Scheduler, not root permissions.

If you need system-level scheduled tasks (running automatically at system startup or requiring root permissions), consider:

1. Using the operating system's crontab -e or systemctl to create system-level scheduled tasks directly.
2. Creating an MCP Scheduler task that executes a script to manage system-level scheduled tasks.

Persistence and Service Management

To ensure that MCP Scheduler continues to run after a system restart, you can:

1. Set it up as a system service (using systemd).
2. Start it automatically when the user logs in.
3. Run it as a container or service in a cloud environment.

📚 Documentation

MCP Tool Functions

The MCP Scheduler provides the following tools:

Task Management

• list_tasks: Get all scheduled tasks.
• get_task: Get details of a specific task.
• add_command_task: Add a new shell command task.
• add_api_task: Add a new API call task.
• add_ai_task: Add a new AI task.
• add_reminder_task: Add a new reminder task with desktop notification.
• update_task: Update an existing task.
• remove_task: Delete a task.
• enable_task: Enable a disabled task.
• disable_task: Disable an active task.
• run_task_now: Run a task immediately.

Execution and Monitoring

• get_task_executions: Get execution history for a task.
• get_server_info: Get server information.

Cron Expression Guide

MCP Scheduler uses standard cron expressions for scheduling. Here are some examples:

• 0 0 * * * - Daily at midnight.
• 0 */2 * * * - Every 2 hours.
• 0 9-17 * * 1-5 - Every hour from 9 AM to 5 PM, Monday to Friday.
• 0 0 1 * * - At midnight on the first day of each month.
• 0 0 * * 0 - At midnight every Sunday.

Environment Variables

The scheduler can be configured using environment variables:

• MCP_SCHEDULER_NAME: Server name (default: mcp-scheduler).
• MCP_SCHEDULER_VERSION: Server version (default: 0.1.0).
• MCP_SCHEDULER_ADDRESS: Server address (default: localhost).
• MCP_SCHEDULER_PORT: Server port (default: 8080).
• MCP_SCHEDULER_TRANSPORT: Transport mode (default: stdio).
• MCP_SCHEDULER_LOG_LEVEL: Logging level (default: INFO).
• MCP_SCHEDULER_LOG_FILE: Log file path.
• MCP_SCHEDULER_DB_PATH: Database path (default: scheduler.db).
• MCP_SCHEDULER_CHECK_INTERVAL: How often to check for tasks (default: 5 seconds).
• MCP_SCHEDULER_EXECUTION_TIMEOUT: Task execution timeout (default: 300 seconds).
• MCP_SCHEDULER_AI_MODEL: OpenAI model for AI tasks (default: gpt-4o).
• MCP_SCHEDULER_USE_AWS_Q_MODEL: Use AWS Q model for AI tasks (default: false).
• OPENAI_API_KEY: API key for OpenAI tasks (not needed when using AWS Q model).

Usage Examples

Using through Amazon Q (Recommended)

Using Amazon Q to create and manage tasks is very simple. Just describe the tasks you want using natural language:

1. Create a Command Task:

   Create a scheduled task to backup my database to the /backups directory every night at 10:30 PM.
   

2. Create an API Call Task:

   Set up a task to get weather data every 6 hours.
   

3. Create an AI Task:

   Generate a summary report of last week's sales data every Monday at 9:00 AM.
   

4. Create a Reminder Task:

   Remind me to attend the team meeting every Tuesday and Thursday at 9:30 AM.
   

5. View All Tasks:

   Show all scheduled tasks.
   

6. Run a Task Immediately:

   Run the backup task now.
   

Using through the Programming API

If you are developing an application or script, you can interact with MCP Scheduler programmatically. Here is a brief guide on establishing a call relationship:

1. Install the necessary dependencies

# Install using uv (recommended)
uv pip install "mcp[client]>=1.4.0"

2. Establish a connection and call the API

import asyncio
from mcp.client import StdioClient

async def main():
    # Start MCP Scheduler as a subprocess
    process_args = ["uv", "run", "/path/to/scheduler-mcp/main.py"]
    async with StdioClient.create_subprocess(process_args) as client:
        # Get server information
        server_info = await client.call("get_server_info")
        print(f"Connected to {server_info['name']} version {server_info['version']}")
        
        # List all tasks
        tasks = await client.call("list_tasks")
        print(f"There are currently {len(tasks)} tasks.")
        
        # Add a command task
        cmd_task = await client.call(
            "add_command_task", 
            {
                "name": "System Status Check",
                "schedule": "*/30 * * * *",  # Every 30 minutes
                "command": "vmstat > /tmp/vmstat_$(date +%Y%m%d_%H%M).log",
                "description": "Record system status",
                "do_only_once": False
            }
        )
        print(f"Created command task: {cmd_task['id']}")
        
        # Run a task immediately
        run_result = await client.call(
            "run_task_now", 
            {"task_id": cmd_task['id']}
        )
        print(f"Task execution result: {run_result['execution']['status']}")

# Run the main function
if __name__ == "__main__":
    asyncio.run(main())

3. Connect to a running MCP Scheduler

If MCP Scheduler is already running in HTTP mode, you can use the SSE client to connect:

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"There are currently {len(tasks)} tasks.")

asyncio.run(connect_to_running_scheduler())

4. Error Handling

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 error: {e}")
                return []
    except Exception as e:
        print(f"Connection error: {e}")
        return []

asyncio.run(robust_scheduler_client())

Complete Example

Check examples/api_client_example.py for a complete API usage example, including:

• Connecting to the MCP Scheduler service.
• Creating, running, updating, and deleting tasks.
• Getting task execution history.
• Error handling and exception management.

# Run the example
cd examples
./api_client_example.py

Example Scripts

The examples directory contains ready-to-use scripts and configurations for common use cases:

• backup_mcp_config.sh: A script for backing up the Amazon Q MCP configuration file, including date-based naming and retention policies.

MCP Tool Discovery

MCP Scheduler supports automatic tool discovery through the Model Context Protocol:

Stdio Mode (Default)

When running in stdio mode (the default), tool discovery happens automatically through the MCP protocol. This is the recommended mode for use with Amazon Q and other MCP clients that support stdio communication.

# Run in stdio mode (default)
uv run main.py

HTTP Mode (Optional)

If you need to run the server in HTTP mode, you can use the SSE transport and access the schema through the well-known endpoint:

# Run with HTTP server transport
uv run main.py --transport sse --port 8080

In HTTP mode, the server exposes a well-known endpoint for tool/schema auto-discovery:

• Endpoint: /.well-known/mcp-schema.json (on the HTTP port + 1, e.g., if your server runs on 8080, the schema is on 8081).
• Purpose: Allows clients and AI assistants to discover all available MCP tools and their parameters automatically.

You can access the schema at:

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

Example Schema Response

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

This schema is generated automatically from the registered MCP tools and always reflects the current server capabilities.

🔧 Technical Details

The scheduler uses cron expressions for flexible timing and provides a complete history of task executions. It's built on the Model Context Protocol (MCP), making it easy to integrate with AI assistants and other MCP-compatible clients. The server automatically handles the communication protocol based on the environment, whether it's stdio or HTTP.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.