{"id":27604041,"url":"https://github.com/jolks/mcp-cron","last_synced_at":"2026-04-01T23:50:29.065Z","repository":{"id":287681922,"uuid":"965110422","full_name":"jolks/mcp-cron","owner":"jolks","description":"MCP server for scheduling and running shell commands and AI prompts","archived":false,"fork":false,"pushed_at":"2026-03-22T16:11:34.000Z","size":405,"stargazers_count":18,"open_issues_count":2,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-23T01:53:57.878Z","etag":null,"topics":["anthropic","automation","claude","cron","cursor","mcp","mcp-server","openai","scheduler"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jolks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["jolks"]}},"created_at":"2025-04-12T12:40:55.000Z","updated_at":"2026-03-22T16:10:14.000Z","dependencies_parsed_at":"2026-02-11T03:19:02.992Z","dependency_job_id":null,"html_url":"https://github.com/jolks/mcp-cron","commit_stats":null,"previous_names":["jolks/mcp-cron"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/jolks/mcp-cron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jolks%2Fmcp-cron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jolks%2Fmcp-cron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jolks%2Fmcp-cron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jolks%2Fmcp-cron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jolks","download_url":"https://codeload.github.com/jolks/mcp-cron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jolks%2Fmcp-cron/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["anthropic","automation","claude","cron","cursor","mcp","mcp-server","openai","scheduler"],"created_at":"2025-04-22T19:23:37.181Z","updated_at":"2026-04-01T23:50:29.056Z","avatar_url":"https://github.com/jolks.png","language":"Go","funding_links":["https://github.com/sponsors/jolks"],"categories":[],"sub_categories":[],"readme":"# MCP Cron\n\nModel Context Protocol (MCP) server for scheduling and managing tasks through a standardized API. The server provides task scheduling capabilities supporting both shell commands and AI-powered tasks, all accessible via the MCP protocol.\n\n## Features\n\n- Schedule shell command or prompt to AI tasks using cron expressions\n- AI can have access to MCP servers \n- [Manage tasks](#available-mcp-tools) via MCP protocol\n- Task execution with command output capture\n- Task persistence across restarts (SQLite)\n- Multi-instance safe — multiple instances can share the same database without duplicate execution\n- Support multiple isolated instances with different `--db-path`\n\n## Installation\n\n### npm (recommended)\n\n```bash\nnpx -y mcp-cron\n```\n\n#### Claude Code\n```bash\nclaude mcp add mcp-cron -- npx -y mcp-cron\n```\n\n#### Cursor / Claude Desktop\n```json\n{\n  \"mcpServers\": {\n    \"mcp-cron\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-cron\", \"--transport\", \"stdio\"]\n    }\n  }\n}\n```\n\n#### Recommended Configuration\n\nA more complete setup with AI provider, model selection, and sleep prevention:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-cron\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"mcp-cron\",\n        \"--transport\", \"stdio\",\n        \"--prevent-sleep\",\n        \"--ai-provider\", \"anthropic\",\n        \"--ai-model\", \"claude-sonnet-4-5-20250929\"\n      ],\n      \"env\": {\n        \"ANTHROPIC_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n#### Using LiteLLM\n\nTo route AI tasks through a [LiteLLM](https://docs.litellm.ai/) proxy:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-cron\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"mcp-cron\",\n        \"--transport\", \"stdio\",\n        \"--prevent-sleep\",\n        \"--ai-base-url\", \"https://litellm.yourcompany.com\",\n        \"--ai-model\", \"claude-sonnet-4-5-20250929\"\n      ],\n      \"env\": {\n        \"MCP_CRON_AI_API_KEY\": \"sk-your-litellm-key\"\n      }\n    }\n  }\n}\n```\n\n\u003e The `--ai-model` value should match a model name in your LiteLLM proxy config. LiteLLM exposes an OpenAI-compatible API, so `--ai-provider` can be omitted (defaults to `openai`). When a custom base URL is set, mcp-cron automatically uses the Chat Completions API instead of the Responses API. The Responses API is only used for direct OpenAI (`api.openai.com`) and Azure OpenAI (`*.openai.azure.com`) endpoints.\n\n\u003e See [Command Line Arguments](#command-line-arguments) and [Environment Variables](#environment-variables) for all available options.\n\n### Building from Source\n\n#### Prerequisites\n- Go 1.24.0 or higher\n\n```bash\n# Clone the repository\ngit clone https://github.com/jolks/mcp-cron.git\ncd mcp-cron\n\n# Build the application as mcp-cron binary\ngo build -o mcp-cron cmd/mcp-cron/main.go\n```\n\n## Usage\nThe server supports two transport modes:\n- **HTTP (Streamable HTTP)**: Default HTTP-based transport for browser and network clients\n- **stdio**: Standard input/output transport for direct piping and inter-process communication\n\n| Client | Config File Location |\n|--------|----------------------|\n| Cursor | `~/.cursor/mcp.json` |\n| Claude Desktop (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json`|\n| Claude Desktop (Windows) | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n\n### HTTP (Streamable HTTP)\n\n```bash\n# Start the server with Streamable HTTP transport (default mode)\n# Default to localhost:8080\n./mcp-cron\n\n# Start with custom address and port\n./mcp-cron --address 127.0.0.1 --port 9090\n```\nConfig file example\n```json\n{\n  \"mcpServers\": {\n    \"mcp-cron\": {\n      \"url\": \"http://localhost:8080\"\n    }\n  }\n}\n```\n\n### stdio\nThe stdio transport is particularly useful for:\n- Direct piping to/from other processes\n- Integration with CLI tools\n- Testing in environments without HTTP\n- Docker container integration\n\nUpon starting Cursor IDE and Claude Desktop, it will **automatically** start the server\n\nConfig file example\n```json\n{\n  \"mcpServers\": {\n    \"mcp-cron\": {\n      \"command\": \"\u003cpath to where mcp-cron binary is located\u003e/mcp-cron\",\n      \"args\": [\"--transport\", \"stdio\"]\n    }\n  }\n}\n```\n\n### Command Line Arguments\n\nThe following command line arguments are supported:\n\n| Argument | Description | Default |\n|----------|-------------|---------|\n| `--address` | The address to bind the server to | `localhost` |\n| `--port` | The port to bind the server to | `8080` |\n| `--transport` | Transport mode: `http` or `stdio` | `http` |\n| `--log-level` | Logging level: `debug`, `info`, `warn`, `error`, `fatal` | `info` |\n| `--log-file` | Log file path | stdout |\n| `--version` | Show version information and exit | `false` |\n| `--ai-provider` | AI provider: `openai` or `anthropic` | `openai` |\n| `--ai-base-url` | Custom base URL for OpenAI-compatible endpoints (e.g. Ollama, vLLM, Groq, LiteLLM) | Not set |\n| `--ai-model` | AI model to use for AI tasks | `gpt-4o` |\n| `--ai-max-iterations` | Maximum iterations for tool-enabled AI tasks | `20` |\n| `--mcp-config-path` | Path to MCP configuration file | `~/.cursor/mcp.json` |\n| `--db-path` | Path to SQLite database for result history | `~/.mcp-cron/results.db` |\n| `--prevent-sleep` | Prevent system from sleeping while mcp-cron is running (macOS and Windows) | `false` |\n| `--poll-interval` | How often to check for due tasks | `1s` |\n\n### Environment Variables\n\nThe following environment variables are supported:\n\n| Environment Variable | Description | Default |\n|----------------------|-------------|---------|\n| `MCP_CRON_SERVER_ADDRESS` | The address to bind the server to | `localhost` |\n| `MCP_CRON_SERVER_PORT` | The port to bind the server to | `8080` |\n| `MCP_CRON_SERVER_TRANSPORT` | Transport mode: `http` or `stdio` | `http` |\n| `MCP_CRON_SERVER_NAME` | **Deprecated** — ignored; the server name is fixed to ensure self-reference detection works correctly | - |\n| `MCP_CRON_SERVER_VERSION` | **Deprecated** — ignored; version is set at build time via ldflags | - |\n| `MCP_CRON_SCHEDULER_DEFAULT_TIMEOUT` | Default timeout for task execution | `10m` |\n| `MCP_CRON_LOGGING_LEVEL` | Logging level: `debug`, `info`, `warn`, `error`, `fatal` | `info` |\n| `MCP_CRON_LOGGING_FILE` | Log file path | stdout |\n| `MCP_CRON_AI_PROVIDER` | AI provider: `openai` or `anthropic` | `openai` |\n| `MCP_CRON_AI_BASE_URL` | Custom base URL for OpenAI-compatible endpoints (e.g. Ollama, vLLM, Groq, LiteLLM) | Not set |\n| `MCP_CRON_AI_API_KEY` | Generic fallback API key (used when provider-specific key is not set) | Not set |\n| `OPENAI_API_KEY` | OpenAI API key for AI tasks | Not set |\n| `ANTHROPIC_API_KEY` | Anthropic API key for AI tasks | Not set |\n| `MCP_CRON_ENABLE_OPENAI_TESTS` | Enable OpenAI integration tests | `false` |\n| `MCP_CRON_AI_MODEL` | LLM model to use for AI tasks | `gpt-4o` |\n| `MCP_CRON_AI_MAX_TOOL_ITERATIONS` | Maximum iterations for tool-enabled tasks | `20` |\n| `MCP_CRON_MCP_CONFIG_FILE_PATH` | Path to MCP configuration file | `~/.cursor/mcp.json` |\n| `MCP_CRON_STORE_DB_PATH` | Path to SQLite database for result history | `~/.mcp-cron/results.db` |\n| `MCP_CRON_PREVENT_SLEEP` | Prevent system from sleeping while mcp-cron is running (macOS and Windows) | `false` |\n| `MCP_CRON_POLL_INTERVAL` | How often to check for due tasks (Go duration format) | `1s` |\n\n### Sleep Prevention\n\nOn laptops, the system may go to sleep and prevent scheduled tasks from running on time. Use the `--prevent-sleep` flag to keep the system awake while mcp-cron is running:\n\n```bash\nmcp-cron --prevent-sleep --transport stdio\n```\n\nOr via environment variable:\n```bash\nMCP_CRON_PREVENT_SLEEP=true mcp-cron --transport stdio\n```\n\n| Platform | Mechanism | Notes |\n|----------|-----------|-------|\n| macOS | `caffeinate` | Prevents idle sleep; automatically cleans up on exit |\n| Windows | `SetThreadExecutionState` | Prevents idle sleep; automatically cleans up on exit |\n| Linux | Not supported | Linux servers typically do not auto-sleep |\n\n\u003e **Note:** This prevents idle sleep only. It does not prevent sleep from closing the laptop lid or pressing the power button.\n\n### Logging\n\nWhen running with the default HTTP transport, logs are output to the console. \n\nWhen running with stdio transport, logs are redirected to a `mcp-cron.log` log file to prevent interference with the JSON-RPC protocol:\n- Log file location: Same location as `mcp-cron` binary.\n- Task outputs, execution details, and server diagnostics are written to this file.\n- The stdout/stderr streams are kept clean for protocol messages only.\n\n### Available MCP Tools\n\nThe server exposes several tools through the MCP protocol:\n\n1. `list_tasks` - Lists all tasks (scheduled and on-demand)\n2. `get_task` - Gets a specific task by ID\n3. `add_task` - Adds a new shell command task (provide `schedule` for recurring, or omit for on-demand)\n4. `add_ai_task` - Adds a new AI (LLM) task with a prompt (provide `schedule` for recurring, or omit for on-demand)\n5. `update_task` - Updates an existing task\n6. `remove_task` - Removes a task by ID\n7. `run_task` - Immediately executes a task by ID (for on-demand tasks or ad-hoc runs of scheduled tasks)\n8. `enable_task` - Enables a task so it runs on its schedule or can be triggered via `run_task`\n9. `disable_task` - Disables a task so it stops running and cannot be triggered\n10. `get_task_result` - Gets execution results for a task (latest by default, or recent history with `limit`)\n11. `query_task_result` - Runs a read-only SQL query against the database (SELECT only, capped at 1000 rows)\n\n### Task Format\n\nTasks have the following structure:\n\n```json\n{\n  \"id\": \"task_a3f7b2c9e1d04f68\",\n  \"name\": \"Example Task\",\n  \"schedule\": \"0 */5 * * * *\",\n  \"command\": \"echo 'Task executed!'\",\n  \"prompt\": \"Analyze yesterday's sales data and provide a summary\",\n  \"type\": \"shell_command\",\n  \"description\": \"An example task that runs every 5 minutes\",\n  \"enabled\": true,\n  \"lastRun\": \"2025-01-01T12:00:00Z\",\n  \"nextRun\": \"2025-01-01T12:05:00Z\",\n  \"status\": \"completed\",\n  \"createdAt\": \"2025-01-01T00:00:00Z\",\n  \"updatedAt\": \"2025-01-01T12:00:00Z\"\n}\n```\n\nFor shell command tasks, use the `command` field to specify the command to execute.\nFor AI tasks, use the `prompt` field to specify what the AI should do.\nThe `type` field can be either `shell_command` (default) or `AI`.\n\n**Scheduled vs on-demand tasks:**\n- **Scheduled**: Provide a `schedule` (cron expression) — the task runs automatically on that schedule.\n- **On-demand**: Omit `schedule` — the task sits idle until triggered via `run_task`.\n\n`run_task` also works on scheduled tasks for ad-hoc execution outside their normal schedule. After execution, scheduled tasks resume their normal schedule; on-demand tasks return to idle.\n\n### Task Status\n\nThe tasks can have the following status values:\n- `pending` - Task has not been run yet\n- `running` - Task is currently running\n- `completed` - Task has successfully completed\n- `failed` - Task has failed during execution\n- `disabled` - Task is disabled and won't run on schedule\n\n### Cron Expression Format\n\nCron expressions are required for scheduled tasks and omitted for on-demand tasks. The scheduler uses the [github.com/robfig/cron/v3](https://github.com/robfig/cron) library for parsing. The format includes seconds:\n\n```\n┌───────────── second (0 - 59) (Optional)\n│ ┌───────────── minute (0 - 59)\n│ │ ┌───────────── hour (0 - 23)\n│ │ │ ┌───────────── day of the month (1 - 31)\n│ │ │ │ ┌───────────── month (1 - 12)\n│ │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)\n│ │ │ │ │ │\n│ │ │ │ │ │\n* * * * * *\n```\n\nExamples:\n- `0 */5 * * * *` - Every 5 minutes (at 0 seconds)\n- `0 0 * * * *` - Every hour\n- `0 0 0 * * *` - Every day at midnight\n- `0 0 12 * * MON-FRI` - Every weekday at noon\n\n## Development\n\n### Building\n\n```bash\ngo build -o mcp-cron cmd/mcp-cron/main.go\n```\n\n### Testing\n\nSee [docs/testing.md](docs/testing.md) for the full testing guide, including integration tests and AI task tests.\n\n## Acknowledgments\n\n- [modelcontextprotocol/go-sdk](https://github.com/modelcontextprotocol/go-sdk) - Official Go SDK for the Model Context Protocol\n- [robfig/cron](https://github.com/robfig/cron) - Cron expression parsing for Go\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjolks%2Fmcp-cron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjolks%2Fmcp-cron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjolks%2Fmcp-cron/lists"}