MCP Scheduler is a versatile task automation server that lets you define and manage a variety of tasks through the MCP protocol. It supports four task types: running shell commands, making API calls, generating content with AI models, and sending desktop reminders with notifications. Tasks are scheduled using standard cron expressions, enabling both one-time runs and recurring schedules. You can view execution history, monitor task status, and control tasks (enable/disable, run immediately) through the MCP toolset. This makes it easy to connect the scheduler to MCP-compatible assistants and clients for automated workflows.

Once running, you can manage tasks via the built-in MCP Tool Functions, including adding new command-based tasks, API tasks, AI tasks, and reminder tasks. You can also fetch execution histories for auditing and diagnostics, and retrieve server information to monitor health and configuration. For AI tasks, you can specify prompts and models (e.g., GPT-4o) to produce generated content or summaries as part of automated pipelines. Reminders leverage desktop notifications with optional sounds to alert users at scheduled times. The scheduler’s cron-based timing provides precise control over when each task executes, and the system maintains robust logs and error handling to help you troubleshoot any failures.

Prerequisites:

• Python 3.10 or higher
• git
• Optional: uv (recommended) for enhanced environment setup

Install from source:

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

2. Create and activate a Python virtual environment python -m venv .venv

   Unix/macOS

   source .venv/bin/activate

   Windows

   .venv\Scripts\activate

3. Install dependencies pip install -r requirements.txt

4. Run the server (default stdio transport) python main.py

Optional: run with a specific transport or port (see usage options for details) python main.py --transport sse --port 8080

Notes:

• If you plan to use AI tasks, set OPENAI_API_KEY in your environment or in a config file.
• You can also install uv and use it for a more advanced local environment as described in the README.

Tips and troubleshooting:

• Ensure Python 3.10+ is active in your shell when creating the virtual environment.
• If you modify environment variables, restart the server to pick up changes.
• For Claude Desktop or other MCP clients, ensure the server address and port match your deployment configuration.
• Check the scheduler_db file (default scheduler.db) permissions to prevent write errors.
• Use the --debug flag for detailed stack traces when troubleshooting task failures.
• If an API task requires authentication, securely store keys and avoid hard-coding them in scripts.