克劳德调度程序
安排Claude Code代理在特定时间或定期运行，具有可选的MCP服务器访问和精细的权限控制。
概述
Claude Scheduler是一个命令行工具，允许您安排Claude Code SDK任务在无人值守的情况下运行。你可以：
- 在特定时间安排一次性任务（例如“下午2:30”）
- 按时间间隔（例如每3600秒）安排重复任务
- 加载MCP服务器以访问工具（电子邮件、日历、任务管理器等）
- 预先授权用于无人值守执行的特定工具
安装
# Clone/download the project
cd claude_scheduler
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt快速开始
# Run the scheduler
python3 main.py
# Schedule a task
> schedule 2:30PM --mcps lookout --allow Send Alice a dad joke
# List scheduled tasks
> list
# Exit (saves state)
> exit命令
| 命令 | 描述 |
|---|---|
schedule | 在特定时间安排任务 |
periodic | 安排定期任务 |
list | 显示所有计划任务 |
unschedule | 按索引删除任务 |
save-prompt | 将任务提示保存到文件 |
mcps | 列出可用的MCP服务器 |
save | 将计划保存到磁盘 |
reload | 从磁盘重新加载计划 |
help | 显示帮助（使用 help 详情） |
exit | 保存状态并退出 |
命令语法
日程
在特定时间安排Claude任务。
schedule [options]
选项：
--mcps name1,name2-加载指定的MCP服务器--cwd /path-设置工作目录（继承项目上下文）--prompt-file /path-从文件读取提示（用于长提示）--allow-预先授权所有加载的MCP，以便无人值守执行--allow patterns-仅预先授权特定工具
示例：
# Basic task (will prompt for permissions if needed)
> schedule 9:00AM Check the weather
# With MCP, authorize all its tools
> schedule 2:30PM --mcps lookout --allow Send Alice a dad joke
# Authorize only specific tool
> schedule 9:00AM --mcps lookout --allow lookout:read_inbox Check my morning emails
# Multiple specific tools
> schedule 10:00AM --mcps lookout --allow lookout:read_inbox,lookout:send_mail Read and reply to urgent emails
# Wildcard tool patterns
> schedule 3:00PM --mcps lookout --allow lookout:mail_* Handle all mail tasks
# Multiple MCPs, authorize only one
> schedule 12:00PM --mcps lookout,aidderall --allow aidderall Summarize my tasks
# Long prompt from file (bypasses shell line length limits)
> schedule 9:00AM --mcps lookout --allow --prompt-file ~/prompts/morning_briefing.txt周期性的
安排一个重复的Claude任务。
periodic [options]
示例：
# Every hour, check tasks
> periodic 3600 --mcps aidderall --allow Summarize my open tasks
# Every 5 minutes, check for urgent emails
> periodic 300 --mcps lookout --allow lookout:read_inbox Check for urgent emails
# Long prompt from file
> periodic 900 --mcps lookout --allow --prompt-file ~/prompts/calendar_check.txt列表
显示所有计划任务及其索引、计划和选项。
> list
Scheduled tasks:
0> "Send Alice a dad joke" at 02:30PM (mcps=[lookout], allow=[lookout])
1> "Check for urgent emails" every 300s (mcps=[lookout], allow=[lookout:read_inbox])取消安排
按索引删除任务。
> unschedule 0
Removed task 0保存提示
将任务提示保存到文件中。可用于编辑或重新创建日程条目。
# Save task 0's prompt to a file
> save-prompt 0 ~/prompts/morning_briefing.txt
Saved prompt to /Users/you/prompts/morning_briefing.txt (847 chars)
# Edit the file, then recreate the task
> unschedule 0
> schedule 9:00AM --mcps lookout --allow --prompt-file ~/prompts/morning_briefing.txtmcps
列出从加载的可用MCP服务器 ~/.claude.json.
> mcps
Available MCP servers (3):
(from ~/.claude.json)
lookout (sse)
aidderall (stdio)
dataremote (stdio)
Use 'mcps --verbose' for details
> mcps --verbose
# Shows full config including source project paths帮助
获取命令帮助。
> help
Available commands:
==================================================
exit - Exit the scheduler, saving state.
help - List all available commands with usage info.
list - List all scheduled tasks.
...
==================================================
Type 'help ' for detailed usage
> help schedule
schedule:
Schedule a Claude task at a specific time.
Usage: schedule [options]
...权限系统
默认情况下，Claude在使用工具时会提示权限。对于计划/无人值守的任务，您需要使用预授权工具 --allow.
权限模式
MCP工具 （需要冒号）：
| 模式 | 允许 |
|---|---|
--allow （无参数） | 所有加载的MCP中的所有工具 |
--allow lookout: | 所有工具来自 lookout （尾部冒号=全部） |
--allow lookout:send_mail | 只有 send_mail 从 lookout |
--allow lookout:mail_* | 通配符匹配（例如。， mail_send, mail_read) |
--allow lookout:,aidderall: | 多个MCP |
内置工具:
| 模式 | 允许 |
|---|---|
--allow Bash | Shell命令执行 |
--allow Edit | 文件编辑 |
--allow Write | 文件创建 |
--allow Read | 文件读取 |
--allow Edit,Write | 多种内置工具 |
组合的:
# MCP + built-in tools
> schedule 9:00AM --mcps lookout --allow lookout:read_inbox,Bash Check mail and run cleanup安全考虑
- 仅预先授权每项任务所需的最低工具
- 使用特定的工具模式(
lookout:send_mail)而不是毯子(lookout:) - 内置工具，如
Bash功能强大-请谨慎使用 - 任务没有
--allow将提示权限（在无人值守模式下失败）
坚持
任务计划保存到 claude_schedule.pickle 退出时恢复，启动时恢复。
> exit
Saving schedule state...
Saved 2 task(s) to claude_schedule.pickle
Goodbye!
# Later...
$ python3 main.py
Claude Scheduler v1.0
========================================
Loaded 2 task(s) from claude_schedule.pickle
...MCP服务器配置
MCP服务器从您的Claude代码配置加载到 ~/.claude.json。首先在Claude Code中配置它们，然后它们将在调度器中可用。
调度器从Claude配置中的所有项目中抓取MCP配置-使用 mcps 命令查看可用内容。
运行测试
# Run all tests
python3 tests/test_parser.py
# Or with pytest (if installed)
python -m pytest tests/ -v建筑
claude_scheduler/
├── main.py # Entry point, CLI commands
├── command_line.py # REPL command processor framework
├── scheduler.py # Background task scheduler thread
├── claude_task.py # ClaudeTask class (SDK integration)
├── mcp_registry.py # MCP config loader from ~/.claude.json
└── tests/
└── test_parser.py框图
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLAUDE SCHEDULER │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌─────────────────────────────────────────────┐ │
│ │ User CLI │ │ main.py │ │
│ │ │────────▶│ ClaudeSchedulerCommandProcessor │ │
│ │ > schedule │ │ │ │
│ │ > periodic │ │ Commands: │ │
│ │ > list │ │ • parse_task_args() │ │
│ │ > unschedule│ │ • schedule / periodic │ │
│ │ > mcps │ │ • save / reload │ │
│ └──────────────┘ └──────────────┬──────────────────────────────┘ │
│ │ │
│ │ creates │
│ ▼ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ mcp_registry.py │ │ claude_task.py │ │
│ │ │◀──────────│ │ │
│ │ MCPRegistry │ lookups │ ClaudeTask │ │
│ │ • ~/.claude.json │ │ • prompt │ │
│ │ • get() │ │ • mcps[] │ │
│ │ • list_servers() │ │ • allowed_tools │ │
│ └───────────────────┘ │ • cwd │ │
│ └─────────┬─────────┘ │
│ │ │
│ │ added to │
│ ▼ │
│ ┌───────────────────┐ │
│ ┌────────────────────┐ │ scheduler.py │ │
│ │ claude_schedule │◀────────▶│ │ │
│ │ .pickle │ save/ │ TaskScheduler │ │
│ │ │ load │ (Thread) │ │
│ │ Persisted tasks │ │ │ │
│ └────────────────────┘ │ polls every 1s │ │
│ │ ┌───────────┐ │ │
│ │ │ task_list │ │ │
│ │ └─────┬─────┘ │ │
│ └─────────┼─────────┘ │
│ │ │
│ │ when due: execute() │
│ ▼ │
│ ┌───────────────────┐ │
│ │ Background Thread│ │
│ │ │ │
│ │ _run_agent() │ │
│ │ │ │ │
│ └───────┼───────────┘ │
│ │ │
└──────────────────────────────────────────┼──────────────────────────────────┘
│
▼
┌───────────────────────┐
│ claude_code_sdk │
│ │
│ query( │
│ prompt, │
│ allowed_tools, │
│ mcps │
│ ) │
└───────────┬───────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ MCP: mail │ │ MCP: tasks │ │ Bash/Edit │
│ (lookout) │ │ (aidderall)│ │ /Write │
└────────────┘ └────────────┘ └────────────┘流量：
- 用户输入命令→
parse_task_args()提取选项 ClaudeTask使用提示、MCP、允许的工具创建- 任务已添加到
TaskScheduler线程列表 - 调度程序每秒轮询一次，检查
should_activate() - 到期时→ 生成异步线程→ calls
claude_code_sdk.query() - 代理使用配置的MCP和工具权限运行
安全说明
Pickle文件：使用Python的 pickle 模块(claude_schedule.pickle).Pickle文件在加载时可以执行任意代码。 切勿从不受信任的来源加载pickle文件。 只使用你自己创建的pickle文件。
如果您需要在机器之间共享时间表，请使用 save-prompt 将提示导出为纯文本文件，然后在目标计算机上重新创建任务。
许可证
麻省理工学院