{"id":28323743,"url":"https://github.com/phialsbasement/scheduler-mcp","last_synced_at":"2025-10-06T00:43:04.886Z","repository":{"id":291488550,"uuid":"977776848","full_name":"PhialsBasement/scheduler-mcp","owner":"PhialsBasement","description":"MCP Scheduler is a task automation server that lets you schedule shell commands, API calls, AI tasks, and desktop notifications using cron expressions. Built with Model Context Protocol for seamless integration with Claude Desktop and other AI assistants.","archived":false,"fork":false,"pushed_at":"2025-06-14T02:42:13.000Z","size":37,"stargazers_count":18,"open_issues_count":2,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-24T01:39:27.895Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PhialsBasement.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-04T23:49:00.000Z","updated_at":"2025-06-24T00:23:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"f1948593-96bd-454a-9809-a3fd721add99","html_url":"https://github.com/PhialsBasement/scheduler-mcp","commit_stats":null,"previous_names":["phialsbasement/scheduler-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/PhialsBasement/scheduler-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhialsBasement%2Fscheduler-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhialsBasement%2Fscheduler-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhialsBasement%2Fscheduler-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhialsBasement%2Fscheduler-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PhialsBasement","download_url":"https://codeload.github.com/PhialsBasement/scheduler-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PhialsBasement%2Fscheduler-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264005170,"owners_count":23542829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-25T16:14:43.998Z","updated_at":"2025-10-06T00:43:04.873Z","avatar_url":"https://github.com/PhialsBasement.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Scheduler\n\nA robust task scheduler server built with Model Context Protocol (MCP) for scheduling and managing various types of automated tasks.\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n\n## Overview\n\nMCP Scheduler is a versatile task automation system that allows you to schedule and run different types of tasks:\n\n- **Shell Commands**: Execute system commands on a schedule\n- **API Calls**: Make HTTP requests to external services\n- **AI Tasks**: Generate content through OpenAI models\n- **Reminders**: Display desktop notifications with sound\n\nThe 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.\n\n## Features\n\n- **Multiple Task Types**: Support for shell commands, API calls, AI content generation, and desktop notifications\n- **Cron Scheduling**: Familiar cron syntax for precise scheduling control\n- **Run Once or Recurring**: Option to run tasks just once or repeatedly on schedule\n- **Execution History**: Track successful and failed task executions\n- **Cross-Platform**: Works on Windows, macOS, and Linux\n- **Interactive Notifications**: Desktop alerts with sound for reminder tasks\n- **MCP Integration**: Seamless connection with AI assistants and tools\n- **Robust Error Handling**: Comprehensive logging and error recovery\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10 or higher\n- [uv](https://astral.sh/uv) (recommended package manager)\n\n### Installing uv (recommended)\n\n```bash\n# For Mac/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# For Windows (PowerShell)\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\nAfter installing uv, restart your terminal to ensure the command is available.\n\n### Project Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/phialsbasement/mcp-scheduler.git\ncd mcp-scheduler\n\n# Create and activate a virtual environment with uv\nuv venv\nsource .venv/bin/activate  # On Unix/MacOS\n# or\n.venv\\Scripts\\activate     # On Windows\n\n# Install dependencies with uv\nuv pip install -r requirements.txt\n```\n\n### Standard pip installation (alternative)\n\nIf you prefer using standard pip:\n\n```bash\n# Clone the repository\ngit clone https://github.com/phialsbasement/mcp-scheduler.git\ncd mcp-scheduler\n\n# Create and activate a virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Unix/MacOS\n# or\n.venv\\Scripts\\activate     # On Windows\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n## Usage\n\n### Running the Server\n\n```bash\n# Run with default settings (stdio transport)\npython main.py\n\n# Run with server transport on specific port\npython main.py --transport sse --port 8080\n\n# Run with debug mode for detailed logging\npython main.py --debug\n```\n\n### Integrating with Claude Desktop or other MCP Clients\n\nTo use your MCP Scheduler with Claude Desktop:\n\n1. Make sure you have Claude Desktop installed\n2. Open your Claude Desktop App configuration at:\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n3. Create the file if it doesn't exist, and add your server:\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"type\": \"stdio\",\n      \"name\": \"MCP Scheduler\",\n      \"command\": \"python\",\n      \"args\": [\"/path/to/your/mcp-scheduler/main.py\"]\n    }\n  ]\n}\n```\n\nAlternatively, use the `fastmcp` utility if you're using the FastMCP library:\n\n```bash\n# Install your server in Claude Desktop\nfastmcp install main.py --name \"Task Scheduler\"\n```\n\n### Command Line Options\n\n```\n--address        Server address (default: localhost)\n--port           Server port (default: 8080)\n--transport      Transport mode (sse or stdio) (default: stdio)\n--log-level      Logging level (default: INFO)\n--log-file       Log file path (default: mcp_scheduler.log)\n--db-path        SQLite database path (default: scheduler.db)\n--config         Path to JSON configuration file\n--ai-model       AI model to use for AI tasks (default: gpt-4o)\n--version        Show version and exit\n--debug          Enable debug mode with full traceback\n--fix-json       Enable JSON fixing for malformed messages\n```\n\n### Configuration File\n\nYou can use a JSON configuration file instead of command-line arguments:\n\n```json\n{\n  \"server\": {\n    \"name\": \"mcp-scheduler\",\n    \"version\": \"0.1.0\",\n    \"address\": \"localhost\",\n    \"port\": 8080,\n    \"transport\": \"sse\"\n  },\n  \"database\": {\n    \"path\": \"scheduler.db\"\n  },\n  \"logging\": {\n    \"level\": \"INFO\",\n    \"file\": \"mcp_scheduler.log\"\n  },\n  \"scheduler\": {\n    \"check_interval\": 5,\n    \"execution_timeout\": 300\n  },\n  \"ai\": {\n    \"model\": \"gpt-4o\",\n    \"openai_api_key\": \"your-api-key\"\n  }\n}\n```\n\n## MCP Tool Functions\n\nThe MCP Scheduler provides the following tools:\n\n### Task Management\n\n- `list_tasks`: Get all scheduled tasks\n- `get_task`: Get details of a specific task\n- `add_command_task`: Add a new shell command task\n- `add_api_task`: Add a new API call task\n- `add_ai_task`: Add a new AI task\n- `add_reminder_task`: Add a new reminder task with desktop notification\n- `update_task`: Update an existing task\n- `remove_task`: Delete a task\n- `enable_task`: Enable a disabled task\n- `disable_task`: Disable an active task\n- `run_task_now`: Run a task immediately\n\n### Execution and Monitoring\n\n- `get_task_executions`: Get execution history for a task\n- `get_server_info`: Get server information\n\n## Cron Expression Guide\n\nMCP Scheduler uses standard cron expressions for scheduling. Here are some examples:\n\n- `0 0 * * *` - Daily at midnight\n- `0 */2 * * *` - Every 2 hours\n- `0 9-17 * * 1-5` - Every hour from 9 AM to 5 PM, Monday to Friday\n- `0 0 1 * *` - At midnight on the first day of each month\n- `0 0 * * 0` - At midnight every Sunday\n\n## Environment Variables\n\nThe scheduler can be configured using environment variables:\n\n- `MCP_SCHEDULER_NAME`: Server name (default: mcp-scheduler)\n- `MCP_SCHEDULER_VERSION`: Server version (default: 0.1.0)\n- `MCP_SCHEDULER_ADDRESS`: Server address (default: localhost)\n- `MCP_SCHEDULER_PORT`: Server port (default: 8080)\n- `MCP_SCHEDULER_TRANSPORT`: Transport mode (default: stdio)\n- `MCP_SCHEDULER_LOG_LEVEL`: Logging level (default: INFO)\n- `MCP_SCHEDULER_LOG_FILE`: Log file path\n- `MCP_SCHEDULER_DB_PATH`: Database path (default: scheduler.db)\n- `MCP_SCHEDULER_CHECK_INTERVAL`: How often to check for tasks (default: 5 seconds)\n- `MCP_SCHEDULER_EXECUTION_TIMEOUT`: Task execution timeout (default: 300 seconds)\n- `MCP_SCHEDULER_AI_MODEL`: OpenAI model for AI tasks (default: gpt-4o)\n- `OPENAI_API_KEY`: API key for OpenAI tasks\n\n## Examples\n\n### Adding a Shell Command Task\n\n```python\nawait scheduler.add_command_task(\n    name=\"Backup Database\",\n    schedule=\"0 0 * * *\",  # Midnight every day\n    command=\"pg_dump -U postgres mydb \u003e /backups/mydb_$(date +%Y%m%d).sql\",\n    description=\"Daily database backup\",\n    do_only_once=False  # Recurring task\n)\n```\n\n### Adding an API Task\n\n```python\nawait scheduler.add_api_task(\n    name=\"Fetch Weather Data\",\n    schedule=\"0 */6 * * *\",  # Every 6 hours\n    api_url=\"https://api.weather.gov/stations/KJFK/observations/latest\",\n    api_method=\"GET\",\n    description=\"Get latest weather observations\",\n    do_only_once=False\n)\n```\n\n### Adding an AI Task\n\n```python\nawait scheduler.add_ai_task(\n    name=\"Generate Weekly Report\",\n    schedule=\"0 9 * * 1\",  # 9 AM every Monday\n    prompt=\"Generate a summary of the previous week's sales data.\",\n    description=\"Weekly sales report generation\",\n    do_only_once=False\n)\n```\n\n### Adding a Reminder Task\n\n```python\nawait scheduler.add_reminder_task(\n    name=\"Team Meeting\",\n    schedule=\"30 9 * * 2,4\",  # 9:30 AM every Tuesday and Thursday\n    message=\"Don't forget the team standup meeting!\",\n    title=\"Meeting Reminder\",\n    do_only_once=False\n)\n```\n\n## MCP Auto-discovery Endpoint\n\nWhen running in SSE (HTTP) mode, MCP Scheduler exposes a well-known endpoint for tool/schema auto-discovery:\n\n- **Endpoint:** `/.well-known/mcp-schema.json` (on the HTTP port + 1, e.g., if your server runs on 8080, the schema is on 8081)\n- **Purpose:** Allows clients and AI assistants to discover all available MCP tools and their parameters automatically.\n\n### Example\n\nIf you run:\n\n```bash\npython main.py --transport sse --port 8080\n```\n\nYou can access the schema at:\n\n```\nhttp://localhost:8081/.well-known/mcp-schema.json\n```\n\n### Example Response\n\n```json\n{\n  \"tools\": [\n    {\n      \"name\": \"list_tasks\",\n      \"description\": \"List all scheduled tasks.\",\n      \"endpoint\": \"list_tasks\",\n      \"method\": \"POST\",\n      \"parameters\": {\n        \"type\": \"object\",\n        \"properties\": {},\n        \"required\": [],\n        \"additionalProperties\": false\n      }\n    },\n    {\n      \"name\": \"add_command_task\",\n      \"description\": \"Add a new shell command task.\",\n      \"endpoint\": \"add_command_task\",\n      \"method\": \"POST\",\n      \"parameters\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"name\": {\"type\": \"string\"},\n          \"schedule\": {\"type\": \"string\"},\n          \"command\": {\"type\": \"string\"},\n          \"description\": {\"type\": \"string\"},\n          \"enabled\": {\"type\": \"boolean\"},\n          \"do_only_once\": {\"type\": \"boolean\"}\n        },\n        \"required\": [\"name\", \"schedule\", \"command\"],\n        \"additionalProperties\": false\n      }\n    }\n    // ... more tools ...\n  ]\n}\n```\n\nThis schema is generated automatically from the registered MCP tools and always reflects the current server capabilities.\n\n## Development\n\nIf you want to contribute or develop the MCP Scheduler further, here are some additional commands:\n\n```bash\n# Install the MCP SDK for development\nuv pip install \"mcp[cli]\u003e=1.4.0\"\n\n# Or for FastMCP (alternative implementation)\nuv pip install fastmcp\n\n# Testing your MCP server\n# With the MCP Inspector tool\nmcp inspect --stdio -- python main.py\n\n# Or with a simple MCP client\npython -m mcp.client.stdio python main.py\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Built on the [Model Context Protocol](https://modelcontextprotocol.io/)\n- Uses [croniter](https://github.com/kiorky/croniter) for cron parsing\n- Uses [OpenAI API](https://openai.com/blog/openai-api) for AI tasks\n- Uses [FastMCP](https://github.com/jlowin/fastmcp) for enhanced MCP functionality\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphialsbasement%2Fscheduler-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphialsbasement%2Fscheduler-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphialsbasement%2Fscheduler-mcp/lists"}