claudecron

phildougherty/claudecron

3.2

If you are the rightful owner of claudecron and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Claudecron is an MCP server designed to automate tasks within Claude Code, enabling users to schedule and trigger various actions based on events or file changes.

Tools
11
Resources
0
Prompts
0

claudecron

Schedule tasks in Claude Code. Run bash commands, AI prompts, or slash commands based on cron schedules, Claude Code hooks, or file changes.

What it does

This is an MCP server that lets you automate stuff in Claude Code. You can:

  • Run bash commands on a schedule or when files change
  • Trigger AI tasks when certain events happen (like session start)
  • Execute slash commands automatically
  • Chain tasks together with dependencies
  • React to Claude Code events (file edits, tool usage, etc.)

Installation

You need Node.js 18 or later.

cd mcp-server
npm install
npm run build

Configure as MCP Server

Add this to your Claude Code MCP configuration. The location depends on your OS:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "claudecron": {
      "command": "node",
      "args": ["/absolute/path/to/claudecron/mcp-server/dist/server.js"]
    }
  }
}

Replace /absolute/path/to/claudecron with the actual path.

Restart Claude Code after adding the configuration.

Basic Usage

Once the MCP server is running, you can create tasks from within Claude Code.

Create a scheduled task

Ask Claude to create a task:

Create a claudecron task that backs up my database every day at 2 AM

Claude will use the claudecron_add_task tool to create it. Here's what that looks like:

{
  "name": "Daily Database Backup",
  "type": "bash",
  "task_config": {
    "type": "bash",
    "command": "pg_dump mydb > backups/mydb-$(date +%Y%m%d).sql"
  },
  "trigger": {
    "type": "schedule",
    "cron": "0 2 * * *",
    "timezone": "UTC"
  }
}

Create a hook-based task

Run something when you edit files:

Create a task that runs prettier whenever I save a TypeScript file

This creates a task like:

{
  "name": "Auto-format TypeScript on Save",
  "type": "bash",
  "task_config": {
    "type": "bash",
    "command": "prettier --write \"$FILE_PATH\""
  },
  "trigger": {
    "type": "hook",
    "event": "PostToolUse",
    "conditions": {
      "tool_names": ["Write", "Edit"],
      "file_pattern": ".*\\.tsx?$"
    },
    "debounce": "2s"
  }
}

Create an AI task

Run AI prompts automatically:

Create a task that summarizes my git commits when I start a session

This creates:

{
  "name": "Session Startup Report",
  "type": "subagent",
  "task_config": {
    "type": "subagent",
    "prompt": "Review recent git commits and provide a brief summary of work since last session.",
    "inherit_context": true,
    "allowed_tools": ["Bash", "Read"]
  },
  "trigger": {
    "type": "hook",
    "event": "SessionStart"
  }
}

Task Types

bash - Execute shell commands

Run any shell command with full environment control.

Good for: builds, tests, file operations, git commands, scripts

Example:

{
  "type": "bash",
  "command": "npm test",
  "cwd": "/path/to/project",
  "timeout": 60000
}

subagent - Execute prompts via Claude SDK

Run any AI prompt with full Claude SDK capabilities.

Good for: code review, analysis, refactoring, documentation, complex multi-step workflows

Example (inline prompt):

{
  "type": "subagent",
  "prompt": "Review the code changes and summarize",
  "model": "claude-sonnet-4.5",
  "inherit_context": true,
  "allowed_tools": ["Read", "Grep"],
  "capture_thinking": true
}

Example (load from .claude/commands/):

{
  "type": "subagent",
  "command": "review-pr",
  "args": "123",
  "stream_output": true
}

Subagent config options:

  • prompt - Inline prompt (supports {{template_vars}})
  • command - Load prompt from .claude/commands/{command}.md
  • args - Arguments to append to command
  • model - Model to use (default: claude-sonnet-4.5)
  • inherit_context - Load CLAUDE.md context (default: true)
  • allowed_tools - Restrict available tools
  • additional_context - Extra context to append
  • capture_thinking - Capture thinking blocks (Claude 4.5+)
  • stream_output - Stream results in real-time
  • max_thinking_tokens - Extended thinking token limit
  • sdk_options - Override any SDK option

Triggers

schedule - Cron-based scheduling

{
  "type": "schedule",
  "cron": "0 9 * * 1-5",
  "timezone": "America/New_York"
}

hook - React to Claude Code events

{
  "type": "hook",
  "event": "PostToolUse",
  "conditions": {
    "tool_names": ["Write", "Edit"],
    "file_pattern": ".*\\.ts$"
  },
  "debounce": "2s"
}

Available hook events:

  • SessionStart - When Claude Code starts or resumes
  • SessionEnd - When session ends
  • PreToolUse - Before any tool is used
  • PostToolUse - After any tool is used
  • UserPromptSubmit - When user submits a prompt
  • SubagentStop - When a subagent finishes
  • Stop - When user stops Claude
  • PreCompact - Before context compaction
  • Notification - Custom notifications

file_watch - Watch files for changes

{
  "type": "file_watch",
  "path": "src/**/*.ts",
  "debounce": "5s"
}

dependency - Run after other tasks complete

{
  "type": "dependency",
  "depends_on": ["task-id-1", "task-id-2"],
  "require_all": true
}

interval - Run every X minutes/hours

{
  "type": "interval",
  "every": "30m"
}

manual - Only run when explicitly triggered

{
  "type": "manual",
  "description": "Run this manually via claudecron_run_task"
}

MCP Tools

These tools are available in Claude Code once the server is running:

  • claudecron_add_task - Create a new task
  • claudecron_list_tasks - List all tasks
  • claudecron_get_task - Get task details
  • claudecron_update_task - Update a task
  • claudecron_delete_task - Delete a task
  • claudecron_run_task - Manually run a task
  • claudecron_list_executions - See execution history
  • claudecron_get_execution - Get execution details
  • claudecron_get_execution_progress - Check running task status
  • claudecron_trigger_hook - Manually trigger a hook (for testing)
  • claudecron_get_tool_analytics - Get usage statistics

Managing Tasks

List all tasks:

Show me all my claudecron tasks

Run a task manually:

Run the task named "Daily Database Backup"

Check execution history:

Show me the last 10 task executions

Delete a task:

Delete the task named "Auto-format TypeScript on Save"

Configuration for Subagent Tasks

Subagent tasks can use MCP tools if you configure them. Create a .mcp.json file in your project:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Now AI tasks running in your project can use those MCP tools. Note: This is different from Claude Code's main MCP config. Tasks run in their own execution environment.

Examples

Check the examples/hook-tasks.json file for more task examples including:

  • Auto-formatting on save
  • Running tests when files change
  • Session startup reports
  • Commit message generation
  • Cleanup on session end
  • Linting on save
  • Build on config changes
  • Weekly dependency reports

Important Notes

  • Tasks run in an isolated environment
  • They don't have access to Claude Code's MCP servers by default
  • Use .mcp.json in your project to give AI tasks access to specific MCP servers
  • Hook tasks can see file paths via template variables like $FILE_PATH
  • Cron expressions support seconds (6 fields) or standard 5-field format
  • Timezones use IANA format (e.g., America/New_York, Europe/London)

Development

Build:

npm run build

Watch mode:

npm run dev

Run tests:

npm test

Type check:

npm run type-check

Storage

Tasks and execution history are stored in SQLite. Default location is ~/.claude/claudecron/tasks.db.

License

MIT