Crontab MCP Server

A Model Context Protocol (MCP) server for managing cron jobs through the node-crontab library. This server enables LLMs to create, read, update, and delete cron jobs via the MCP protocol.

Features

• Create cron jobs with custom schedules and commands
• List all jobs with filtering and pagination
• Get specific job details by identifier
• Update existing jobs (schedule, command, or comment)
• Delete jobs by identifier or command pattern
• Support for both JSON and Markdown output formats
• Special schedule support (@reboot, @daily, @weekly, etc.)
• Multi-user support (with sudo privileges)

Installation

npm install
npm run build

Tools

The server exposes five MCP tools:

1. crontab_list_jobs

List all cron jobs with optional filtering and pagination.

Parameters:

• limit (number, optional): Maximum jobs to return (1-100, default: 50)
• offset (number, optional): Pagination offset (default: 0)
• filter_command (string, optional): Filter by command pattern (regex)
• filter_comment (string, optional): Filter by comment pattern (regex)
• user (string, optional): Target user's crontab (requires sudo)
• response_format ('markdown' | 'json', optional): Output format (default: 'markdown')

Example:

{
  "limit": 10,
  "filter_comment": "backup"
}

2. crontab_get_job

Retrieve details of a specific job by its comment/identifier.

Parameters:

• comment (string, required): Job identifier
• user (string, optional): Target user's crontab (requires sudo)
• response_format ('markdown' | 'json', optional): Output format (default: 'markdown')

Example:

{
  "comment": "daily-backup"
}

3. crontab_create_job

Create a new cron job with a command and optional schedule.

Parameters:

• command (string, required): Shell command to execute
• schedule (string, optional): Cron expression (e.g., '0 2 * * *') or special schedule (@daily, @hourly, @weekly, @monthly, @yearly, @reboot, @midnight, @annually)
• comment (string, optional): Job identifier for easy reference
• user (string, optional): Target user's crontab (requires sudo)
• response_format ('markdown' | 'json', optional): Output format (default: 'markdown')

Example:

{
  "command": "/usr/local/bin/backup.sh",
  "schedule": "0 2 * * *",
  "comment": "daily-backup"
}

4. crontab_update_job

Update an existing cron job's command, schedule, or comment.

Parameters:

• comment (string, required): Current job identifier
• new_command (string, optional): New command
• new_schedule (string, optional): New schedule
• new_comment (string, optional): New identifier
• user (string, optional): Target user's crontab (requires sudo)
• response_format ('markdown' | 'json', optional): Output format (default: 'markdown')

Example:

{
  "comment": "daily-backup",
  "new_schedule": "0 3 * * *"
}

5. crontab_delete_job

Delete one or more cron jobs by comment or command.

Parameters:

• comment (string, optional): Job identifier to delete
• command (string, optional): Command pattern for deletion (exact match)
• user (string, optional): Target user's crontab (requires sudo)

At least one of comment or command must be provided.

Example:

{
  "comment": "daily-backup"
}

Cron Schedule Format

Standard Cron Expression

Five fields: minute hour day-of-month month day-of-week

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 7) (Sunday is 0 or 7)
│ │ │ │ │
* * * * *

Examples:

• 0 2 * * * - Run at 2:00 AM every day
• */15 * * * * - Run every 15 minutes
• 0 9-17 * * 1-5 - Run hourly from 9 AM to 5 PM on weekdays
• 0 0 1 * * - Run at midnight on the first day of each month

Special Schedules

• @reboot - Run once at system startup
• @hourly - Run once every hour
• @daily or @midnight - Run once every day at midnight
• @weekly - Run once every week at midnight on Sunday
• @monthly - Run once every month at midnight on the first day
• @yearly or @annually - Run once every year at midnight on January 1st

Usage with MCP Clients

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "crontab": {
      "command": "node",
      "args": ["/path/to/crontab-mcp/dist/index.js"]
    }
  }
}

Other MCP Clients

The server uses stdio transport and can be integrated with any MCP client that supports stdio.

Response Formats

Markdown Format (Default)

Human-readable output with formatted text:

# Cron Jobs

Found 2 jobs (showing 2)

## daily-backup
- **Schedule**: `0 2 * * *` (Cron schedule: 0 2 * * *)
- **Command**: /usr/local/bin/backup.sh
- **Comment**: daily-backup
- **Enabled**: Yes

## weekly-cleanup
- **Schedule**: `@weekly` (Weekly at midnight Sunday)
- **Command**: rm -rf /tmp/old_files
- **Comment**: weekly-cleanup
- **Enabled**: Yes

JSON Format

Structured data for programmatic processing:

{
  "total": 2,
  "count": 2,
  "offset": 0,
  "jobs": [
    {
      "command": "/usr/local/bin/backup.sh",
      "schedule": "0 2 * * *",
      "comment": "daily-backup",
      "enabled": true
    },
    {
      "command": "rm -rf /tmp/old_files",
      "schedule": "@weekly",
      "comment": "weekly-cleanup",
      "enabled": true
    }
  ],
  "has_more": false
}

Error Handling

The server provides clear, actionable error messages:

• Permission denied: Indicates insufficient permissions to access crontab
• Invalid schedule: Shows correct syntax and lists valid special schedules
• Job not found: Suggests using crontab_list_jobs to find available jobs
• Duplicate comment: Recommends using crontab_update_job or choosing a different identifier

Requirements

• Node.js >= 18
• System with cron installed
• Appropriate permissions to manage crontab

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Development mode with auto-reload
npm run dev

# Clean build artifacts
npm run clean

Security Considerations

• The server requires appropriate system permissions to manage crontab
• Multi-user operations (using the user parameter) require sudo privileges
• All job deletions are permanent and cannot be undone
• Input validation prevents common injection attacks

License

MIT

Author

Created with the MCP Builder skill following MCP best practices.