Skip to main content
Glama
Sign In
deenesjakoruzh
kimai-timelog-mcp

kimai-timelog-mcp

by Alpha101Code
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

kimai-timelog-mcp

tests

一个 MCP 服务器，让 Claude（或任何支持 MCP 的 LLM 客户端）读取和写入你的 Kimai 工时表。你说 “把 9 点到 12:30 记到门户改版上，修复登录重定向”，条目就会出现在 Kimai 中。

每个请求都以你的身份发起——它使用你的个人 Kimai API 令牌，因此只能查看和更改你的 Kimai 账户被允许访问的内容。

1. 获取 Kimai API 令牌

  1. 打开 Kimai → 点击你的名字（右上角）→ 我的个人资料 → API 访问 选项卡。

  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 上，如果 PATH 中找不到 uvx，请使用 uvx.exe。

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

与 Claude Desktop 的 JSON 结构相同，放在该客户端的 MCP 配置文件中（Cursor 为 ~/.cursor/mcp.json）。

其他客户端

它是一个标准的 stdio MCP 服务器。命令：kimai-mcp。配置：上面的两个环境变量。

工具

工具

用途

whoami

令牌属于谁、他们的时区、今天的日期

list_projects

你可以记账的项目，可按名称搜索

list_activities

对项目有效的活动（项目专属 + 全局）

list_customers

你可以看到的客户

list_tags

在 Kimai 中配置的标签名称

list_timesheets

某个日期范围内你的条目，含总计

recent_entries

你最近的项目/活动/描述组合

summarize_time

按项目、活动或日期汇总的工时

log_time

写入一条已完成的条目

start_timer

开始一条运行中的条目

active_timers

当前正在运行的内容

stop_timer

停止正在运行的条目

restart_timer

将旧条目克隆为新的运行中条目

update_timesheet

修改现有条目

delete_timesheet

删除条目（需要显式确认）

值得了解的设计选择

  • 名称，而非 ID。 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 通信。它没有其他网络访问权限，没有文件系统访问权限，也没有 shell。

  • 如果你的 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）。服务器在导入时自动选择正确的版本；预期中的失败会继承 SDK 的 ToolError，这样消息就能到达模型，而不是显示通用的“error executing tool”。测试套件在 CI 中针对两者运行。

该发行版名为 kimai-timelog-mcp（与仓库同名）；它安装的命令是 kimai-mcp。

基于 Kimai 2 REST API（/api，Authorization: Bearer <token>）构建。端点参考：https://www.kimai.org/documentation/rest-api.html 以及你自己实例的 /api/doc。

Available Tools

15 tools
active_timersB

Any currently running time entries for this user.

Inputs: no named parameters. Returns: result

delete_timesheetA

Permanently delete a time entry.

Args: timesheet_id: the entry to delete. confirm: must be true. Show the user what will be deleted first.

Inputs: timesheet_id (required), confirm. Returns: object

list_activitiesA

List activities, optionally the ones valid for a given project.

Args: project: project name or id. Omit to list every activity. search: optional substring filter on the activity name.

Inputs: search, project. Returns: result

list_customersA

List customers visible to this user.

Inputs: no named parameters. Returns: result

list_projectsA

List the projects this user can book time against.

Args: search: optional substring to filter project or customer names. customer: optional customer name or id to scope the list.

Inputs: search, customer. Returns: result

list_tagsA

Tag names configured in this Kimai instance.

Inputs: no named parameters. Returns: result

list_timesheetsA

The user's own time entries for a date range, newest first.

Defaults to the last 7 days. Use this before writing an entry to avoid duplicates, and to answer "what did I log this week".

Args: from_date: 'today', 'monday', '2026-08-24', '3 days ago'. to_date: same formats; defaults to today. project: optional project name or id to filter by. search: optional free-text search over descriptions. limit: maximum entries to return (max 500).

Inputs: limit, search, project, to_date, +1 more. Returns: object

log_timeA

Write a finished time entry to Kimai.

Give either start+end, or start+duration, or duration alone (which books the period ending now). Do not guess missing times — ask the user instead.

Args: project: project name or id. activity: activity name or id, must be valid for the project. description: what was worked on. Strongly recommended. date: 'today', 'yesterday', 'monday', '2026-08-24'. start: '09:00', '9am', '14.30'. end: same formats as start. duration: '1h30m', '90m', '1.5h', '1:30'. tags: optional list of Kimai tag names. billable: optional override of the project default.

Inputs: project (required), activity (required), end, date, +5 more. Returns: object

recent_entriesA

The project/activity/description combinations this user booked most recently.

Best first call for "log the usual" or "same as yesterday" requests.

Inputs: limit. Returns: result

restart_timerA

Start a new running entry that copies an existing one's project/activity.

Inputs: timesheet_id (required). Returns: object

start_timerB

Start a running timer now (or at a given start time today).

Args: project: project name or id. activity: activity name or id. description: what is being worked on. start: optional start time such as '09:00'; defaults to now.

Inputs: project (required), activity (required), start, description. Returns: object

stop_timerA

Stop a running timer.

Args: timesheet_id: which entry to stop. Omit to stop the only running one.

Inputs: timesheet_id. Returns: object

summarize_timeA

Total the user's logged hours over a range, grouped for reporting.

Args: from_date: defaults to 7 days ago. to_date: defaults to today. group_by: 'project', 'activity' or 'day'.

Inputs: to_date, group_by, from_date. Returns: object

update_timesheetA

Change an existing time entry. Only the fields you pass are touched.

Args: timesheet_id: the entry to change (from list_timesheets). date/start/end/duration: same formats as log_time. Passing any of these recomputes the entry's begin and end.

Inputs: timesheet_id (required), end, date, tags, +6 more. Returns: object

whoamiA

Who the Kimai API token belongs to, plus their timezone and today's date.

Call this once at the start of a time-logging conversation so that relative dates ("yesterday") and times are anchored correctly.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct operation: reference data listing, timesheet queries, entry creation, timer control, editing, deletion, and reporting. Even similar tools like list_timesheets and recent_entries are clearly differentiated by what they return.

    Naming Consistency4/5

    The set mostly follows a clear list_ for read-only collections and verb_noun for actions, such as log_time and stop_timer. Minor deviations like active_timers, recent_entries, and whoami break the pattern slightly but remain understandable.

    Tool Count5/5

    At 15 tools, the server covers discovery, logging, timer lifecycle, modifications, deletion, and reporting without feeling bloated. Each tool contributes a meaningful piece of the time-logging workflow.

    Completeness5/5

    The toolset supports a full time-logging lifecycle: lookup reference data, check existing entries, log time, start and stop timers, restart entries, update or delete entries, and summarize hours. It also includes helpful context tools like whoami and recent_entries; admin CRUD for projects or customers is outside the apparent purpose.

    Resources

    Related MCP Connectors

    Related MCP Servers