clockify-mcp-server

Ведите учёт часов по проектам в Clockify, просто попросив своего агента, вместо того чтобы кликать по веб-интерфейсу.

"добавь 4 часа на ACME каждое утро на этой неделе и 4 часа на Evil Corp каждый день после обеда"

→ один запрос на подтверждение, создано 10 записей, всего 40 часов.

Локальный stdio MCP-сервер. Каждый запускает его сам со своим API-ключом — ничего не публикуется и не хостится.

Время всегда локальное, в часовом поясе вашего профиля Clockify. Вы говорите 09:00, сервер читает settings.timeZone из вашего профиля Clockify и конвертирует в UTC. Вам не приходится иметь дело с UTC, и агенту тоже.

Пока не поддерживается: теги, клиенты, работающие таймеры (старт/стоп), редактирование существующих записей, отчёты.

Использование

Всё, что нужно, если вы просто хотите вести учёт времени. Займёт около двух минут.

1. Установите bun (проверено на 1.3.14) и зависимости:

curl -fsSL https://bun.sh/install | bash # install bun if needed
git clone <this-repo> && cd clockify-mcp-server
bun install

Шага сборки нет — bun запускает TypeScript напрямую.

2. Получите свой Clockify API-ключ:

• Clockify → ваш аватар → Preferences → вкладка ADVANCED → Manage API keys → GENERATE NEW

3. Зарегистрируйте сервер у своего агента.

Claude Code — скопируйте как есть, из корня репозитория, который вы только что склонировали:

claude mcp add clockify -s user -e CLOCKIFY_API_KEY=<key> -- bun "$PWD/src/index.ts"

-s user записывает его в ваш личный конфиг, так что он загружается в каждом проекте, а не только в этом (область по умолчанию, local, привязала бы его к этой директории). $PWD раскрывается вашей оболочкой до того, как его увидит claude, поэтому сохранённый путь абсолютный.

Любая другая среда (Cursor, VS Code, Zed, Claude Desktop…) — те же три вещи в её MCP-конфиге. Выведите путь, чтобы вставить:

echo "$PWD/src/index.ts"

{
  "mcpServers": {
    "clockify": {
      "command": "bun",
      "args": ["<paste the absolute path here>"],
      "env": { "CLOCKIFY_API_KEY": "<key>" }
    }
  }
}

Путь должен быть абсолютным: ваш агент запускает сервер из той директории, в которой он в данный момент работает, а не из этого репозитория.

4. Проверьте — в новой сессии:

list my clockify projects
log 2 hours on <project> today from 09:00 to 11:00, description test
show my clockify entries for this week
delete that entry

Откройте веб-интерфейс Clockify после второго запроса и убедитесь, что запись показывает 09:00–11:00. Если время другое, значит, часовой пояс вашего профиля Clockify не тот, что вы думаете, — исправьте его в настройках Clockify, всё здесь от него зависит.

Окружение

Если что-то пошло не так

• CLOCKIFY_API_KEY is not set — ключ не дошёл до процесса сервера. Укажите его в env конфига среды, а не в вашей оболочке.

• Ambiguous project "x". Candidates: … — это намеренно. Сервер отказывается угадывать id; используйте одно из перечисленных имён.

• 404 на каждый запрос — ваше рабочее пространство находится на региональном хосте. Установите CLOCKIFY_API_BASE.

• Записи попадают не в тот час — проверьте часовой пояс вашего профиля Clockify (см. шаг 4).

Разработка

Ничего из этого не нужно, чтобы просто использовать сервер.

bun test      # unit tests, no network
bun run check # biome format + lint, applies fixes
bun run start # start the server on stdio (needs CLOCKIFY_API_KEY)

bun install также устанавливает git-хуки (prepare → lefthook install), так что biome check --write запускается на ваших подготовленных файлах при коммите и повторно добавляет в индекс то, что исправил. Больше ничего настраивать не нужно.

Для локальных запусков bun автоматически загружает .env из корня репозитория, так что gitignored CLOCKIFY_API_KEY=<key> там избавит вас от повторного ввода. Это работает только когда рабочая директория и есть репозиторий, поэтому конфиг среды выше передаёт ключ явно.

Структура

src/clockify.ts      # API client, memoised user/project/task lookups, timezone conversion
src/index.ts         # McpServer + the four tools + stdio wiring
src/clockify.test.ts # the parts worth testing: DST conversion, name resolution, payload building
docs/                # Clockify API request/response samples
plans/               # what was built and what was deliberately left out

Интересный код — localToUtc / interval в src/clockify.ts — round-trip через Intl.DateTimeFormat из стандартной библиотеки, без библиотек для работы с датами. Измените его и запустите bun test; случаи с переходом на летнее время (DST) — те, что ловят ошибки.

Для передачи тому, у кого нет bun: bun build --compile --outfile clockify-mcp src/index.ts создаёт один самодостаточный бинарник, на который можно указать среде вместо этого.