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