kimai-timelog-mcp

MCP-сервер, который позволяет Claude (или любому MCP-совместимому LLM-клиенту) читать и записывать ваши табели учёта времени в Kimai. Вы говорите «запиши с 9 до 12:30 на редизайн портала, исправление редиректа логина» — и запись появляется в Kimai.

Каждый запрос выполняется от вашего имени — используется ваш личный API-токен Kimai, поэтому сервер может видеть и изменять только то, что разрешено вашей учётной записи Kimai.

1. Получите API-токен Kimai

1. Откройте Kimai → нажмите на своё имя (справа сверху) → Мой профиль → вкладка API access.

2. Создайте токен, дайте ему имя вроде claude и сразу скопируйте его — Kimai показывает его ровно один раз.

Related MCP server: Kimai MCP Server

2. Установка

Вам понадобится uv (рекомендуется) или Python 3.10+.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Затем выберите:

A. Из общей папки / git-репозитория (так сделают коллеги)

uvx --from git+https://github.com/Alpha101Code/kimai-timelog-mcp kimai-mcp --check

B. Из локальной копии

cd /path/to/kimai-timelog-mcp
uv run kimai-mcp --check

--check проверяет URL и токен и выводит ваши видимые проекты. Сначала задайте две переменные окружения:

export KIMAI_URL=https://timesheet-sd.maccs.mu
export KIMAI_API_TOKEN=your-token-here

3. Подключение к вашему клиенту

Claude Desktop

Настройки → Разработчик → Изменить конфигурацию, затем добавьте:

{
  "mcpServers": {
    "kimai": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Alpha101Code/kimai-timelog-mcp", "kimai-mcp"],
      "env": {
        "KIMAI_URL": "https://timesheet-sd.maccs.mu",
        "KIMAI_API_TOKEN": "your-token-here"
      }
    }
  }
}

Перезапустите Claude Desktop. В Windows используйте uvx.exe, если uvx не найден в PATH.

Claude Code

claude mcp add kimai \
  --env KIMAI_URL=https://timesheet-sd.maccs.mu \
  --env KIMAI_API_TOKEN=your-token-here \
  -- uvx --from git+https://github.com/Alpha101Code/kimai-timelog-mcp kimai-mcp

Cursor / Windsurf / Cline / Zed

Та же JSON-структура, что и для Claude Desktop, в файле конфигурации MCP соответствующего клиента (~/.cursor/mcp.json для Cursor).

Остальные клиенты

Это стандартный stdio MCP-сервер. Команда: kimai-mcp. Конфигурация: две переменные окружения выше.

Инструменты

Полезные особенности, о которых стоит знать

• Названия, а не идентификаторы. project: "Portal Revamp" работает; так же работает уникальный частичный вариант "portal". Неоднозначные названия возвращаются как ошибка со списком кандидатов, которую модель может передать вам как вопрос.

• Гибкий ввод времени. date: today, yesterday, monday, 3 days ago, 2026-08-24, 25/08/2026. start/end: 09:00, 9am, 5.30pm, 0930. duration: 1h30m, 90m, 1.5h, 1:30.

• Ваш часовой пояс. Kimai сообщает часовой пояс владельца токена; всё вычисляется относительно него, а не часов сервера.

• Без выдуманных часов. log_time требует start+end, start+duration или duration. Если ничего не указано, возвращается ошибка, в которой модели предлагается спросить вас, а не угадывать.

• Удаление в два шага. Первый вызов возвращает то, что было бы удалено; только второй вызов с confirm: true удаляет запись.

Примеры запросов

Log 9:00–12:30 today on Portal Revamp, development, "fixed the login redirect".
What did I log this week? Break it down by project.
Same as yesterday afternoon, but for today.
Start a timer on Internal Tools / Admin.
I forgot Monday — 4 hours on Mobile App, release testing.
Move entry 512 to start at 10:15 instead.

Внедрение у коллег

Каждому нужны три вещи: установленный uv, собственный токен Kimai и блок конфигурации выше. Ничего не используется совместно — не нужно запускать сервер, нет центрального токена.

Если позже вы захотите один размещённый сервер вместо установки на каждой машине, слой инструментов останется как есть; поменяется только транспорт в __main__.py.

Безопасность

• Токен — эквивалент пароля. Он хранится в файле конфигурации вашего клиента на вашей собственной машине — не коммитьте его и не вставляйте в общий документ.

• Устанавливайте токенам срок действия в Kimai и регулярно их меняйте.

• Сервер общается только с KIMAI_URL. У него нет других сетевых доступов, доступа к файловой системе и оболочки.

• Если ваш Kimai доступен только из внутренней сети, сервер должен запускаться на машине, которая может до него дотянуться (VPN или офисная сеть).

Разработка

src/kimai_mcp/
  client.py     Kimai REST client — auth, errors, name→id resolution, caching
  timeutil.py   parsing for human dates, times and durations
  server.py     the MCP tools
  __main__.py   stdio entrypoint + --check
tests/
  mock_kimai.py a stand-in Kimai instance
  test_e2e.py   drives the real server over stdio against it

Запуск тестового набора (экземпляр Kimai не нужен):

uv run --with mcp --with httpx python tests/test_e2e.py

Совместимость

Работает с обеими основными версиями Python MCP SDK: mcp 1.x (FastMCP) и 2.x (MCPServer). Сервер выбирает нужную версию при импорте, а ожидаемые сбои наследуют ToolError из SDK, поэтому сообщение доходит до модели вместо общего «error executing tool». Набор запускается в CI против обеих версий.

Дистрибутив называется kimai-timelog-mcp (как и репозиторий); устанавливаемая команда — kimai-mcp.

Создано на основе REST API Kimai 2 (/api, Authorization: Bearer <token>). Справочник конечных точек: https://www.kimai.org/documentation/rest-api.html и /api/doc вашего экземпляра.