de en es ja ko ru zh

kimai-timelog-mcp

Name: kimai-timelog-mcp
Author: Alpha101Code

by Alpha101Code

Overview Schema Source Related Servers Discussions Admin

Python

Remote

kimai-timelog-mcp

tests

Claude(またはMCP対応のLLMクライアント)があなたのKimaiタイムシートを読み書きできるようにするMCPサーバーです。*「ポータル改修のログインリダイレクト修正を9時から12:30まで記録して」*と言うだけで、Kimaiにエントリが追加されます。

すべてのリクエストはあなた自身として実行されます — あなた個人のKimai APIトークンを使用するため、あなたのKimaiアカウントに許可された内容しか表示・変更できません。

1. Kimai APIトークンを取得する

Kimaiを開く → 右上の自分の名前をクリック → My profile → API accessタブ。
トークンを作成し、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とトークンを検証し、表示可能なプロジェクトを出力します。先に2つの環境変数を設定してください:

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

3. クライアントに組み込む

Claude Desktop

Settings → Developer → Edit Config の順に開き、以下を追加します:

{
  "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がPATHに見つからない場合は、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。設定: 上記の2つの環境変数です。

ツール

Tool	説明
`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 には開始+終了、開始+所要時間、または所要時間のいずれかが必要です — どれも指定されていない場合は、推測せずにあなたに尋ねるようモデルに伝えるエラーを返します。
削除は2段階。 最初の呼び出しは削除されるであろう内容を返すだけで、confirm: true を付けた2回目の呼び出しでのみ実際に削除されます。

プロンプトの例

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.

同僚への展開

全員に必要なものは3つです: uvのインストール、各自のKimaiトークン、そして上記の設定ブロック。ユーザー間で共有されるものはありません — 実行するサーバーも、中央管理のトークンもありません。

後でマシンごとのインストールではなく、単一のホスト型サーバーが必要になった場合も、ツールレイヤーはそのままで、__main__.py のトランスポートだけが変更されます。

セキュリティ

トークンはパスワードと同等です。自分のマシンにあるクライアントの設定ファイルに保存されます — コミットしたり、共有ドキュメントに貼り付けたりしないでください。
Kimaiでトークンに有効期限を設定し、ローテーションしてください。
サーバーはKIMAI_URLとのみ通信します。他のネットワークアクセス、ファイルシステムアクセス、シェルは一切ありません。
Kimaiが内部限定の場合は、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をサブクラス化するため、汎用的な「ツール実行エラー」ではなく、メッセージがモデルまで届きます。テストスイートは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_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 2026-08-28 01:10 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

Timesheet
io.github.timesheetIO
timesheet.io MCP server - manage timers, projects, tasks and reports
Project Management Workplace & Productivity
11
https://mcp.timesheet.io
TimequipA
com.timequip
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
Project Management Workplace & Productivity
281
https://mcp.timequip.com/mcp
Toggl 2.0
io.github.toggl
Toggl 2.0 MCP server for tasks, projects, time entries, and workspace operations.
Project Management Workplace & Productivity
1
https://focus.toggl.com/mcp
YAARClickUpMCP (Unofficial)
io.github.naderali2235
Unofficial community ClickUp MCP via personal API token. Not affiliated with ClickUp.
Project Management Workplace & Productivity
1
https://clickup-mcp.yaarclickup.workers.dev/mcp

Related MCP Servers

Timesheet MCP Serverofficial
Project Management Workplace & Productivity
timesheetIO
A
license
B
quality
B
maintenance
Enables natural language control of the Timesheet API for timer management, task tracking, and project management through MCP tools.
Updated 8 days ago (2026-11-02 23:32 UTC)
50
103 npm
1
MIT
Kimai MCP Server
Project Management Workplace & Productivity
glazperle
A
license
Not graded
quality
A
maintenance
Enables AI assistants to interact with Kimai time-tracking API for managing timesheets, projects, activities, customers, users, and more.
Updated 13 days ago (2026-10-28 20:38 UTC)
146 PyPI
49
MIT
Clockify Time Tracking
Project Management Workplace & Productivity
tracegazer
A
license
C
quality
C
maintenance
Enables interacting with Clockify time-tracking data through natural language, providing tools to manage workspaces, projects, time entries, reports, and more via the MCP protocol.
Updated 4 months ago (2026-07-20 19:55 UTC)
48
43 PyPI
1
MIT
timing-mcp-server
Project Management Workplace & Productivity
tomoyanakano
A
license
Not graded
quality
D
maintenance
This MCP server enables AI assistants to interact with the Timing application for managing time tracking and tasks, including project and time entry operations.
Updated a year ago (2025-05-11 08:24 UTC)
7
MIT

kimai-timelog-mcp

1. Kimai APIトークンを取得する

2. インストール

3. クライアントに組み込む

Claude Desktop

Claude Code

Cursor / Windsurf / Cline / Zed

その他のクライアント

ツール

知っておくべき設計上のポイント

プロンプトの例

同僚への展開

セキュリティ

開発

互換性

Available Tools

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Related MCP Servers

Timesheet MCP Serverofficial

Kimai MCP Server

Clockify Time Tracking

timing-mcp-server