time-agent-mcp gives LLMs/agents a real clock via MCP, covering current time, elapsed/remaining duration, timezone conversion, session heartbeat, cron checks, and session timers.
current_time: Get current time, date, weekday, timezone, UTC offset, and ISO 8601; optional IANA timezone.
duration_elapsed: Track task start time and elapsed duration; auto-starts on first call, supports reset, custom started_at, task/session ids.
time_until: Count down to a target/deadline; returns remaining time or elapsed time if already past.
timezone_convert: Convert a time between any IANA timezones, with optional source timezone and time.
session_ping: Conversation heartbeat; returns time since last ping and total session duration.
cron_mock: Check whether a schedule is due now using cron, @daily/@hourly macros, or natural syntax like every 30 minutes; returns hit status, next/previous trigger, and countdown without starting real timers.
agent_clock: Session-level timer with start, pause, resume, reset, and status; supports multiple named clocks.
Optional JSON file persistence and LRU session storage; runs over stdio or HTTP for desktop, container, or remote MCP clients.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@time-agent-mcp how long has this task been running so far?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
你开一个 DeepSeek 窗口，说几句话，过几天再问「现在几点了」。 它回答的是第一次对话的时间。不是它笨——是没人给它喂时间。
本地部署（Ollama）/ 第三方中转 / 自建模型的 API 不会像官方那样在 system prompt 里注入当前时间， 于是模型靠训练数据里的记忆猜时间——这就是「时间幻觉」。
这个 MCP Server 给任何 LLM / Agent 框架装一个真正的时钟，并且不只是知道几点： 它还知道任务跑了多久、距离截止还剩多久、东京 vs 纽约是几点。
✅ current_time —— 现在几点/几号/周几/时区（含 UTC 偏移与 ISO 8601）
✅ duration_elapsed —— 任务从何时开始、已过去多久（时间流逝感知，真正的差异化）
✅ time_until —— 距离截止/提醒时刻还剩多久
✅ timezone_convert —— 任意 IANA 时区换算
✅ session_ping —— 会话心跳：感知「对话过了多久」
✅ cron_mock —— 模拟「现在到点了吗」，给定时决策（支持 cron / @宏 / every 30 minutes）
✅ agent_clock —— 会话级计时器：开始 / 暂停 / 恢复 / 重置 / 查询
✅ 零外部运行时依赖（时间源 = 系统时钟，时区 = IANA 内置库）
✅ TypeScript + Python 双版本，npm / pip 即装即用
✅ 支持 Ollama / LangChain / Claude Desktop / 任何 MCP 客户端
Related MCP server: Time MCP Server
# TypeScript 版（stdio，MCP 客户端默认接入）
npm run dev # 开发模式（tsx）
npm run build && node dist/server.js
# TypeScript 版（Streamable HTTP，适合容器/远程）
node dist/server.js --http --port 8787
# Python 版
cd python && python -m time_agent_mcpClaude Desktop（claude_desktop_config.json）：
{
"mcpServers": {
"time-agent": {
"command": "node",
"args": ["D:/project/time-agent-mcp/dist/server.js"]
}
}
}Python 版：
{
"mcpServers": {
"time-agent": {
"command": "python",
"args": ["-m", "time_agent_mcp"],
"cwd": "D:/project/time-agent-mcp/python"
}
}
}工具 | 作用 | 关键参数 |
| 当前时间/日期/星期/时区 |
|
| 任务起始时刻 + 已流逝时长 |
|
| 距离目标时刻的倒计时 |
|
| 时区换算 |
|
| 会话心跳，感知对话间隔 |
|
| 模拟「到点了吗」的定时决策 |
|
| 会话级计时器 |
|
# 现在几点了（上海）
current_time { timezone: "Asia/Shanghai" }
# 任务跑了多久：第一次调用自动开始计时
duration_elapsed { task_id: "scrape-catalog" } # elapsed: 0
# ...10 分钟后再次调用
duration_elapsed { task_id: "scrape-catalog" } # elapsed: 10 分 3 秒
# 距离截稿还剩多久
time_until { target: "2026-10-05T18:00:00", timezone: "Asia/Shanghai" }
# 东京 vs 纽约
timezone_convert { time: "2026-10-01T12:00:00", from_timezone: "Asia/Tokyo", to_timezone: "America/New_York" }
# 对话过了多久
session_ping { session_id: "deepseek-chat-01" }
# 每天 18:00 到点了吗（定时决策）
cron_mock { schedule: "0 18 * * *", timezone: "Asia/Shanghai" }
# 或自然语法
cron_mock { schedule: "every 30 minutes" }
# 会话级计时器：跑批任务计时
agent_clock { clock_id: "batch", action: "start" }
agent_clock { clock_id: "batch", action: "status" } # 查询
agent_clock { clock_id: "batch", action: "pause" } # 暂停
agent_clock { clock_id: "batch", action: "resume" } # 恢复
agent_clock { clock_id: "batch", action: "reset" } # 清零场景 | 官方 API（已注入时间） | 本地部署/中转/自建（未注入） |
「现在几点？」 | 正确 | 幻觉（背的是训练数据里的时间） |
「任务跑了 10 分钟没？」 | 不知道 | 不知道（没人在对话里报时间） |
「还剩几分钟截止？」 | 不知道 | 不知道 |
现有 MCP 方案只解决「现在几点」。time-agent-mcp 差异化在时间流逝感知：
duration_elapsed / session_ping 让 Agent 对自己跑了多久、等了多久有真实感知。
默认内存 Map；设置环境变量 TIME_AGENT_STORE_FILE 可启用 JSON 文件持久化，
重启后仍记得任务起始时刻。TypeScript 与 Python 版本共用同一文件格式。
TIME_AGENT_MAX_SESSIONS（默认 1000）：超过上限按最近活动时间（LRU）淘汰最旧会话，
防止无限膨胀。
返回结果同时含 content（文本 JSON）与 structuredContent（结构化对象），
支持 MCP 的模型层直接消费对象。
模式 | 启动方式 | 场景 |
stdio |
| Claude Desktop / Cline 等桌面客户端 |
HTTP |
| 容器 / 远程 / 集群部署 |
npm install # 安装依赖 + 构建
npm test # 运行测试（TS）
cd python && pip install -e ".[test]" && python -m pytest ../tests_pyM1：TS 版 5 个核心工具 + 示例 + 测试
M2：Python 版 + 测试（双版本行为对齐）+ cron_mock + agent_clock
M3：npm / PyPI 发布
0.3.0：性能优化（cron 跳跃式扫描）、时区往返校验（拒非法日期/DST 空洞）、structuredContent、存储 LRU、HTTP transport、CI
演示 GIF + 各平台推广
与 mcp-doctor（MCP Server 健康检查）同一生态系列： 一个让 Agent 感知时间，一个让 MCP Server 更可靠。
MIT
会话级计时器：start 开始 / pause 暂停 / resume 恢复 / reset 清零 / status 查询，返回累计计时与中文可读时长。
Inputs: action (required), clock_id, timezone, session_id.
定时决策：判断「现在到点了吗」（cron / @宏 / every 30 minutes），返回是否命中、下次与上次触发时刻及倒计时。不启动真实定时器。
Inputs: schedule (required), now, timezone.
返回当前时间、日期、星期、时区与 UTC 偏移（现在几点/几号/周几/时区）。
Inputs: timezone.
任务时长感知：记录任务起始时刻并返回「已过去多久」。首次调用自动开始计时，后续调用返回累计时长；可用 reset=true 重新计时。
Inputs: label, reset, task_id, timezone, +2 more.
会话心跳：每次对话调用一次，更新时间戳并返回距上次对话间隔与本会话总时长，让模型感知对话间隔。
Inputs: timezone, session_id.
倒计时：计算距离目标/截止时刻还剩多久（目标已过则返回已过时长）。
Inputs: target (required), from, timezone.
多时区换算：把某一时刻从源时区换算到目标时区，返回目标时区的本地时间与偏移差。
Inputs: to_timezone (required), time, from_timezone.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 7 tools
Several tools overlap in purpose: agent_clock, time_until, duration_elapsed, and session_ping all measure elapsed or remaining time, making it easy for an agent to pick the wrong one. Descriptions provide some differentiation (session vs task vs target), but boundaries remain blurry.
Mostly consistent snake_case noun/verb phrases (agent_clock, time_until, timezone_convert, session_ping, cron_mock, duration_elapsed, current_time). One minor inconsistency: agent_clock uses a noun where sibling tools use verbs/verb-noun forms, but overall it is predictable.
Seven tools fit the time/session domain reasonably well, though the presence of both agent_clock and duration_elapsed suggests slight redundancy rather than pure over-count.
Covers clock, countdown, timezone conversion, session timing, scheduled decisions, duration tracking, and current time. There is some redundancy (multiple duration tools) rather than missing capabilities; a durable scheduling tool separate from cron_mock might be the only minor gap.
Wall-clock awareness for LLM agents. Two tools: elapsed-time-between-turns + day rollover detection.
A real clock for AI agents: current time, timezone conversion, and DST facts from the IANA tzdb.
Deterministic time tools for AI agents: timezone conversion, business-day math, cron interpretation.
Current time, timezone conversion & date math for AI agents. On Cloudflare Workers.
