cronmanager-mcp

cronmanager-mcp

MCP (Model Context Protocol) server that exposes the Cronmanager REST API as conversational tools for LLM clients such as Claude Desktop or Claude Code.

Example prompts:

• "Show me all failed jobs from the last 24 hours"
• "Disable job 42"
• "Create a maintenance window for Sunday night at 2 AM"
• "Export all jobs tagged 'backup' as JSON"

Requirements

• Cronmanager 4.1.0 or later (external REST API required)
• An API key generated in the Cronmanager web UI (API Keys section)

Quick start

docker run -d \
  -e CM_BASE_URL=https://cronmanager.example.com \
  -e CM_API_KEY=cm_your_api_key_here \
  -e MCP_AUTH_TOKEN=your_mcp_auth_token_here \
  -p 3000:3000 \
  cs1711/cronmanager-mcp:latest

Configure your MCP client to connect to http://your-host:3000/mcp with Bearer token MCP_AUTH_TOKEN.

For integration into an existing Cronmanager Docker Compose stack, see docker-compose.snippet.yml.

Configuration

All configuration is via environment variables.

| Variable | Required | Default | Description | |---|---|---|---| | CM_BASE_URL | yes | — | Cronmanager web app base URL (no trailing slash) | | CM_API_KEY | yes | — | Cronmanager API key (cm_…) | | CM_AGENT_ID | no | — | Target a specific agent (sets X-Agent-Id header) | | MCP_AUTH_TOKEN | yes | — | Bearer token protecting this MCP endpoint | | PORT | no | 3000 | HTTP port | | TIMEOUT_MS | no | 10000 | Cronmanager API request timeout in milliseconds | | LOG_LEVEL | no | info | Log level: debug, info, warn, error | | MCP_READONLY_MODE | no | false | When true, only read-only tools are registered |

API key scopes

The API key must have the scopes matching the tools you intend to use:

| Scope | Tools unlocked | |---|---| | jobs:read | list_jobs, get_job, get_job_history, get_timeline, list_tags | | jobs:write | create_job, update_job, delete_job | | jobs:execute | execute_job, kill_execution | | export:read | export_jobs | | maintenance:read | list_maintenance_windows, get_maintenance_window | | maintenance:write | create_maintenance_window, update_maintenance_window, delete_maintenance_window | | settings:read | get_settings, get_settings_section | | settings:write | update_settings_section, resync_crontab |

For read-only access, use the read-only profile (jobs:read, maintenance:read, export:read) and set MCP_READONLY_MODE=true.

Tools

| Tool | Scope | Description | |---|---|---| | list_jobs | jobs:read | List cron jobs with optional filters | | get_job | jobs:read | Get a single job by ID | | create_job | jobs:write | Create a new cron job | | update_job | jobs:write | Update a job (partial update; targets/tags are full-replaced) | | delete_job | jobs:write | Delete a job | | execute_job | jobs:execute | Trigger immediate one-time execution | | kill_execution | jobs:execute | Kill a running execution | | get_job_history | jobs:read | Execution history for a specific job | | get_timeline | jobs:read | Cross-job execution timeline | | list_tags | jobs:read | List all tags | | export_jobs | export:read | Export jobs as JSON, CSV, or crontab text | | list_maintenance_windows | maintenance:read | List maintenance windows | | get_maintenance_window | maintenance:read | Get a single maintenance window | | create_maintenance_window | maintenance:write | Create a maintenance window | | update_maintenance_window | maintenance:write | Update a maintenance window | | delete_maintenance_window | maintenance:write | Delete a maintenance window | | get_settings | settings:read | Read all agent settings | | get_settings_section | settings:read | Read one settings section | | update_settings_section | settings:write | Update a settings section | | resync_crontab | settings:write | Resync crontab from database |

Note on update_job

If targets or tags are included in an update_job call, they fully replace the existing list — there is no merge. To add a single tag, first call get_job to read the current tags, then pass the complete updated array.

Endpoints

| Endpoint | Description | |---|---| | POST /mcp | MCP Streamable HTTP endpoint (Bearer auth required) | | GET /healthz | Liveness check (always 200, no auth required) | | GET /readyz | Readiness check — pings Cronmanager API (no auth required) |

Security

• The MCP endpoint is protected by a Bearer token (MCP_AUTH_TOKEN), separate from the Cronmanager API key.
• The Cronmanager API key (CM_API_KEY) is never exposed to MCP clients.
• Bind to a specific interface or place behind a reverse proxy if the server should not be publicly accessible.

License

GNU General Public License version 3 or later