Time Manager MCP

Time Manager MCP（STDIO Server）

这是一个基于 SQLite 的 MCP STDIO Server：让 Codex/LLM 通过 MCP tools 读写任务、状态、计划与日志，并返回可口播的指标面板数据。

你通常不需要“手动运行”它；更推荐把它作为 MCP Server 配进 Codex CLI，由 Codex 自动拉起。

解决什么样的痛点

当我们想在一段时间里，学习某项技能，某些知识，同时又担心因为生活并不非如同计划表一样严格可控的时候，这个项目将帮助你协调时间。我曾经在假期里做了非常详尽的计划，但是总因为各种原因不能很好的执行，然后一步乱步步乱，最后离预设的目标很远。但是依赖于ai的灵活性，当我的原定计划被某些因素影响，我不得不调整我的规划的时候，ai就可以出来重新整理规划我的计划，让我在合适的时间里做正确的事，让我把我欠的“债”还好。

它怎么工作

任务与信息入库

在初次使用的时候，用户输入自然语言（当然最好是有规律的，比如：一个b站视频播放列表），然后ai替你把这些东西填到数据库里，变成一条条的结构化数据。

生成明日计划与存档

用户给自然语言告诉ai明日可用时段与精力，ai读取任务、截止日期、最近日志、债务、状态等上下文然后生成计划，给你看，并且写进日志里。

完成汇报与进度更新

每天晚上睡觉之前，跟ai汇报你干了什么，没干什么，它会更新你的状态，并且记录你的债务（没干完的），然后再问他明天该干什么了。

你能得到什么

把“时间规划/复盘/进度统计”变成一组可被 LLM 调用的本地工具：LLM 负责对话与规划，Server 负责把数据可靠地落到 SQLite 并计算面板指标。

• 一个本地 SQLite 数据库（默认在 ./data/app.db），存任务/日志/计划/设置
• 一组 MCP tools（见下方）供 LLM 调用

安装

如果你图省事可以直接让ai替你装（毕竟这只是个无伤大雅的小玩具）

如果你执意自己安装

推荐用 uv，也支持 pip。

# 方式 A：uv
pip install uv
uv pip install -e .

# 方式 B：pip
# pip install -e .

数据库位置（重要）

• 默认数据库：./data/app.db（相对于启动 MCP Server 时的 cwd）
• 想把数据放到仓库外（推荐）：设置环境变量 TIME_MANAGER_MCP_DB_PATH

例如（Windows，建议放 D 盘）：

$env:TIME_MANAGER_MCP_DB_PATH = "D:\\time_manager_mcp\\data\\app.db"

配置到 Codex CLI（推荐用法）

方式 A：codex mcp add

codex mcp add time_manager_mcp -- python -m time_manager_mcp

方式 B：编辑 ~/.codex/config.toml

把 cwd 改成你本机的仓库绝对路径：

[mcp_servers.time_manager_mcp]
command = "python"
args = ["-m", "time_manager_mcp"]
cwd = ""

如果你需要固定数据库路径（推荐），请在启动 Codex 前设置 TIME_MANAGER_MCP_DB_PATH，或者把它写进系统环境变量里。

可用 Tools（给 LLM 调用）

• tasks_upsert
• state_set_current
• plan_save_day
• tasklog_append
• debtlog_append
• settings_set
• context_get_snapshot
• dashboard_get_metrics

最小调用示例（按顺序）

1) tasks_upsert

{
  "tasks": [
    { "title": "线性代数刷题", "category": "math", "course_minutes": 240, "estimate_factor": 1.3 },
    { "title": "Python 刷题", "category": "python", "course_minutes": 180 },
    { "title": "Linux 基础", "category": "linux", "course_minutes": 120 }
  ]
}

2) state_set_current

{
  "energy": "mid",
  "note": "1) 专注/执行状态：轻度疲劳但可持续\n2) 固定约束：01:30 后不学习\n3) 目标变化：优先 python\n4) 环境/资源限制：只有笔记本\n5) 风险与干扰源：消息打断"
}

3) plan_save_day

{
  "date": "2026-01-24",
  "energy": "mid",
  "availability_slots": [{ "start": "19:30", "end": "22:30" }],
  "items": [
    {
      "start": "19:30",
      "end": "20:30",
      "task_id": "YOUR_TASK_ID",
      "minutes": 60,
      "video_from": "45",
      "video_to": "46",
      "note": "看视频 + 做随堂笔记"
    }
  ]
}

4) dashboard_get_metrics

{ "week_start": "2026-01-20", "week_end": "2026-01-26" }

常见问题

我目前没遇到问题，我也不知道这个东西会有什么问题 ，如果真遇到了，就提个issue吧，谢谢了