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

kimai-timelog-mcp

by Alpha101Code
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

kimai-timelog-mcp

tests

Claude(또는 MCP를 지원하는 모든 LLM 클라이언트)가 Kimai 타임시트를 읽고 쓸 수 있게 해주는 MCP 서버입니다. *"포털 개편 작업, 로그인 리다이렉트 수정에 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. 공유 폴더 / 깃 저장소에서 (동료들이 사용할 방식)

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가 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. 구성: 위의 두 환경 변수.

도구

도구

기능

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가 포함된 두 번째 호출에서만 실제로 삭제됩니다.

예시 프롬프트

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의 전송(transport)만 변경하면 됩니다.

보안

  • 토큰은 비밀번호와 동등합니다. 토큰은 사용자 머신의 클라이언트 구성 파일에 저장됩니다. 커밋하지 말고 공유 문서에 붙여넣지 마세요.

  • 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). 서버는 import 시점에 올바른 버전을 선택하며, 예상 가능한 오류는 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_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