temporal-mcp-server
temporal-mcp-server
MCP-сервер с инструментами для времени, часовых поясов и длительностей.
Запускайте его локально через stdio (Claude Desktop, Claude Code, любой локальный MCP-клиент), локально через HTTP или используйте размещённый экземпляр — те же инструменты, тот же код, три способа запуска.
Публичный экземпляр работает на Cloudflare Workers по адресу https://time.somamcp.com/mcp:
claude mcp add --transport http temporal https://time.somamcp.com/mcpПостроен на somamcp, который предоставляет MCP-инфраструктуру, телеметрию и конечные точки здоровья/интроспекции для обеих сред выполнения. Логика времени чистая и функциональная, с использованием functype.
Инструменты
Инструмент | Назначение |
| Текущее время как epoch, UTC ISO-8601 и локальное время в любом часовом поясе IANA |
| Отобразить метку времени ISO-8601 в целевом часовом поясе |
| Прибавить или вычесть длительность ISO-8601 с учётом календарной арифметики месяцев |
| Прошедшее время между двумя метками времени, в целых единицах плюс читаемая сводка |
somamcp также регистрирует инструмент info и конечные точки /health, /health/detail, /info и /dashboard.
Поведение, о котором стоит знать
Арифметика месяцев ограничивает, а не переполняется. add_duration для 2026-01-31 с P1M возвращает 2026-02-28, а не 2026-03-03. Прибавление «одного месяца» к концу длинного месяца приводит к концу короткого.
Смещения определяются для каждого момента, а не для часового пояса. America/New_York сообщает -04:00 в августе и -05:00 в январе. Переход на летнее время берётся из базы данных tz среды выполнения, поэтому здесь нет таблицы смещений, которая могла бы устареть.
Ошибки содержат подсказку. Неизвестный часовой пояс возвращает неверное значение и ожидаемый формат, чтобы вызывающий агент мог исправиться, а не гадать снова.
Related MCP server: mcp-datetimeday
Запуск в качестве локального MCP-сервера
Stdio используется по умолчанию, и это режим, который ожидают локальные клиенты. Ничего не размещается на сервере, ничего не слушает порт — ваш клиент запускает процесс и общается с ним через stdin/stdout.
Claude Code
claude mcp add temporal -- npx -y temporal-mcp-serverClaude Desktop
Добавьте в claude_desktop_config.json:
{
"mcpServers": {
"temporal": {
"command": "npx",
"args": ["-y", "temporal-mcp-server"]
}
}
}На macOS этот файл находится в ~/Library/Application Support/Claude/claude_desktop_config.json; на Windows — %APPDATA%\Claude\claude_desktop_config.json. Перезапустите Claude Desktop после редактирования.
Запуск из клона
Если вы предпочитаете не использовать npm:
pnpm install
pnpm build
pnpm start # stdioЗатем укажите вашему клиенту на собранную точку входа:
claude mcp add temporal -- node /absolute/path/to/temporal-mcp-server/dist/node.js{
"mcpServers": {
"temporal": {
"command": "node",
"args": ["/absolute/path/to/temporal-mcp-server/dist/node.js"]
}
}
}Пакет также устанавливает бинарник temporal-mcp-server, так что глобальная установка (npm i -g temporal-mcp-server) позволяет использовать это имя напрямую как команду.
Проверка работоспособности
Сервер говорит на JSON-RPC через stdout, так что вы можете управлять им вручную:
printf '%s\n%s\n%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0.0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_current_time","arguments":{"timezone":"Asia/Tokyo"}}}' \
| node dist/node.jsТолько JSON-RPC выводится в stdout; логи идут в stderr, так что использование конвейеров безопасно.
Локальный запуск через HTTP
Для клиентов, которые говорят на streamable HTTP, а не на stdio:
pnpm start:http # http://localhost:3333/mcp — override the port with PORTЭто тот же сервер и те же инструменты; отличается только транспорт.
Удалённый запуск на Cloudflare Workers
pnpm cf:dev # local workerd runtime
pnpm cf:deploy # build + edge-safety check + deploycf:deploy сначала запускает pnpm build, который включает check:worker — поэтому бандл, содержащий встроенный модуль Node, не пройдёт проверку до того, как что-либо достигнет Cloudflare.
Непрерывное развёртывание
Деплои выполняются через Cloudflare Workers Builds, а не GitHub Actions, поэтому токен Cloudflare API вообще не хранится в GitHub — Cloudflare подключается к репозиторию через собственное GitHub-приложение.
Настройте это один раз в панели управления (Workers & Pages → temporal-mcp-server → Settings → Build):
Поле | Значение |
Команда деплоя |
|
Команда сборки | (оставьте пустой — |
Корневая директория | (корень репозитория) |
Указание команды деплоя на скрипт пакета сохраняет логику проверок в системе контроля версий; панель управления содержит одну стабильную строку. Имя Worker в панели управления должно совпадать с name в wrangler.jsonc (temporal-mcp-server), иначе сборка завершится ошибкой.
Образ сборки включает pnpm и учитывает .nvmrc (в нашем случае зафиксирован Node 24). Для непроизводственных веток по умолчанию используется npx wrangler versions upload, поэтому пуши в ветки создают предварительные версии, не затрагивая боевой деплой.
Конечная точка MCP находится по адресу /mcp. Чтобы требовать bearer-токен:
wrangler secret put MCP_AUTH_TOKENЕсли задан MCP_AUTH_TOKEN, неаутентифицированные вызовы к /mcp получают 401. Если его не задавать, конечная точка остаётся публичной — разумно для часов, но не для многого другого.
Необязательные vars: GIT_COMMIT и ENVIRONMENT отображаются инструментом info и /info.
Подключение клиента к развёрнутому Worker
Публичный экземпляр обслуживается с пользовательского домена:
claude mcp add --transport http temporal https://time.somamcp.com/mcpЕсли задан токен, передавайте его как заголовок:
claude mcp add --transport http temporal https://time.somamcp.com/mcp \
--header "Authorization: Bearer $MCP_AUTH_TOKEN"Проверка здоровья: https://time.somamcp.com/health.
pnpm cf:dev обслуживает то же самое на http://localhost:8787/mcp, так что вы можете направить клиент на локальный экземпляр workerd перед деплоем.
Почему worker импортирует somamcp/edge
Корневой barrel-модуль somamcp реэкспортирует хелперы, которые импортируют node:fs. Импорт его из Worker тянет встроенные модули Node в бандл. Поэтому src/worker.ts импортирует somamcp/edge, и pnpm check:worker завершает сборку ошибкой, если node:-импорт, голый встроенный модуль Node или корневой спецификатор somamcp попадает в бандл worker.
Проверка проходит по фактическому графу импортов из dist/worker.js, а не сопоставляет имена файлов — бандлер поднимает код, общий с Node-входом, в чанк с сгенерированным именем, и glob по именам файлов пропустил бы именно тот файл, который с наибольшей вероятностью содержит утечку.
nodejs_compat намеренно не включён в wrangler.jsonc. Если встроенный модуль Node когда-либо появится, сборка должна громко упасть, а не быть тихо зашитой.
Блок alias в wrangler.jsonc
xsschema (транзитивно, через fastmcp) проверяет каждую поддерживаемую библиотеку схем — valibot, effect, sury — через динамический импорт. Мы используем только zod, поэтому эти ветки никогда не выполняются, но esbuild всё равно должен разрешать спецификаторы. Для них задаётся псевдоним на пустой модуль вместо установки трёх неиспользуемых библиотек.
Архитектура
src/
clock.ts pure time logic — Either<TemporalError, T>, no I/O, no globals
tools.ts MCP tool registration; takes a server, creates none
index.ts library surface (runtime-agnostic)
node.ts entry: somamcp -> stdio + httpStream
worker.ts entry: somamcp/edge -> export default { fetch }registerTemporalTools(server) принимает сервер, а не создаёт его, поэтому обе точки входа регистрируют одинаковые инструменты. Ничто в clock.ts, tools.ts или index.ts не касается process, файловой системы или любого встроенного модуля Node.
Сбои — это значения. Каждая подверженная ошибкам функция в clock.ts возвращает Either<TemporalError, T>; слой инструментов сводит Left к результату ошибки MCP. Ничто не зависит от разматывания стека, что позволяет одному и тому же коду работать без изменений в обеих средах выполнения.
Разработка
pnpm validate # format + lint + typecheck + test + build
pnpm test # 34 tests
pnpm check:worker # verify the worker bundle is edge-safetest/worker.spec.ts прогоняет реальные объекты Request через fetch-обработчик Worker по MCP-протоколу, поэтому нарушения интеграции всплывают в CI, а не после деплоя.
Лицензия
MIT
Available Tools
5 toolsadd_durationAInspect
Add an ISO-8601 duration to a timestamp, in a timezone. Date units (Y/M/D) are calendar-aware: P1D across a DST boundary keeps the same wall-clock time the next day, and P1M on Jan 31 clamps to the end of February. Time units (H/M/S) are exact elapsed time, so PT24H really is 24 hours. Prefix the duration with '-' to subtract.
Inputs: duration (required), isoTimestamp (required), timezone.
convert_timezoneBInspect
Render an ISO-8601 timestamp as wall-clock time in a target timezone.
Inputs: isoTimestamp (required), targetTimezone (required), sourceTimezone.
get_current_timeAInspect
Return the current time as an epoch, a UTC ISO-8601 timestamp, and the wall-clock time in a given timezone.
Inputs: timezone.
infoARead-onlyInspect
Returns identity and build information for this server (name, version, build commit, runtime, capability counts)
Inputs: no named parameters.
time_betweenAInspect
Exact elapsed time between two ISO-8601 timestamps, broken into days/hours/minutes/seconds plus a human-readable summary. All components share one sign, so they sum correctly; direction is 'past', 'future', or 'same'.
Inputs: to (required), from (required), timezone.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation: server metadata, current time retrieval, timezone conversion, duration arithmetic, and elapsed-time calculation. There is no overlap in inputs or intent, and descriptions make the boundaries unambiguous.
Three tools follow a clean verb_noun pattern (get_current_time, convert_timezone, add_duration), but 'info' is a bare noun and 'time_between' is a prepositional phrase rather than verb-led. The deviations are minor and still readable.
Five tools is well-scoped for a focused time-utility server, with each tool earning its place and no redundant entries. Nothing feels padded or missing at the count level.
The core time lifecycle is covered: now, convert, shift (subtraction handled via negative prefix), and diff. Minor gaps remain around parsing/formatting arbitrary timestamp strings or listing timezones, but agents can work around these.
Maintenance
Related MCP Connectors
Timezone MCP — wraps timeapi.io (free, no auth)
MCP server for time in cities around the world, time zones, DST, conversion, and meetings.
timesheet.io MCP server - manage timers, projects, tasks and reports
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThe Time MCP Server is a Model Context Protocol (MCP) server that provides AI assistants and other MCP clients with standardized tools to perform time and date-related operations. This server acts as a bridge between AI tools and a robust time-handling back167 npm25MIT
- AlicenseAqualityDmaintenanceA lightweight MCP server providing comprehensive date, time, and day-of-week information. It supports relative time calculations, timezone conversions, and detailed calendar metadata like week numbers and quarters.51MIT
- AlicenseDqualityCmaintenanceA lightweight MCP server that provides date and time tools, including the ability to retrieve current timestamps and parse date strings with IANA timezone support. It enables AI models to interact with the host OS clock and perform temporal calculations via stdio transport.310 npm7MIT
- AlicenseAqualityDmaintenanceMCP server providing various date/time functions including current time, timezone conversion, and relative time calculations. Supports both local stdio and remote HTTP access via Cloudflare Workers.26443 npm3MIT