v2.11.2

Fixes

• Correct Work Contract URL in 404 error message

Documentation

• Add release versioning specification to CLAUDE.md

v2.11.1 - Better Work Contract Error Handling

What's New

Improved Error Handling for Work Contract

When calling set_preferences on a user without a configured Work Contract, the MCP now returns a helpful error message instead of just "404 Not Found":

Error: Work Contract not configured for user 28.

The user preferences endpoint returned 404, which means the Work Contract 
has not been set up for this user in Kimai.

Please configure it first in the Kimai UI:
  https://your-kimai.com/en/user/28/work-hours

After setting initial values there, the API will work.

Related

Feature request submitted to Kimai: kimai/kimai#5751

Full Changelog: v2.11.0...v2.11.1

v2.11.0 - Improved LLM Tool Descriptions

What's New

Improved Tool Descriptions for Better LLM Understanding

• COMMON TASKS sections: Each tool now includes examples of common use cases
• Cross-references: Tools reference related tools (e.g., absence tool notes that vacation quota is set via entity tool)
• Preference aliases: More intuitive preference names now work automatically:
  • vacation_days → holidays
  • annual_leave → holidays
  • weekly_hours → hours_per_week
  • contract_type → work_contract_type

Files Changed

• entity_manager.py - Enhanced descriptions + alias system
• timesheet_consolidated.py - Timesheet and timer tool descriptions
• absence_manager.py - Absence types and quota notes
• rate_manager.py - Rate management examples

Full Changelog: v2.10.0...v2.11.0

v2.10.0 - User Preferences Management

What's New

User Preferences Management

New set_preferences action for user entities in the entity tool enables programmatic configuration of work contracts:

• Weekly hours contracts - Set total hours per week (hours_per_week)
• Daily hours contracts - Set individual hours per weekday (work_monday..work_sunday)
• Vacation & holidays - Configure vacation days and public holiday groups
• Contract periods - Define contract start/end dates
• User rates - Set hourly and internal rates

Example Usage

// Weekly contract (40h/week)
entity type=user action=set_preferences id=5 preferences=[
  {"name": "work_contract_type", "value": "week"},
  {"name": "hours_per_week", "value": "144000"},
  {"name": "holidays", "value": "30"}
]

// Daily contract (different hours per day)
entity type=user action=set_preferences id=5 preferences=[
  {"name": "work_contract_type", "value": "day"},
  {"name": "work_monday", "value": "28800"},
  {"name": "work_friday", "value": "14400"}
]

Time Values

All time values are in seconds:

• 8h = 28800 seconds
• 40h = 144000 seconds

See examples/usage_examples.md for complete documentation.

Full Changelog: v2.9.0...v2.10.0

v2.9.0 - Comprehensive Security Module

Security Enhancements

This release adds a comprehensive security module for the HTTP servers, addressing critical vulnerabilities:

✅ Added

• Rate Limiting: Token bucket algorithm to prevent DoS and brute-force attacks (configurable via --rate-limit-rpm)
• Session Management: Maximum concurrent sessions and TTL-based expiration (--max-sessions, --session-ttl)
• Security Headers: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection
• Enumeration Protection: Random delays on 404 responses and automatic blocking after excessive failed requests
• Unit tests for all security components (33 tests)

Configuration

New CLI arguments:

Argument	Default	Description
--rate-limit-rpm	60	Requests per minute per IP
--max-sessions	100	Maximum concurrent sessions
--session-ttl	3600	Session timeout in seconds
--require-https	false	Enforce HTTPS connections

Environment variables: RATE_LIMIT_RPM, MAX_SESSIONS, SESSION_TTL, REQUIRE_HTTPS

v2.8.0 - Streamable HTTP Server for Claude.ai Connectors

New Features

Streamable HTTP Server for Claude.ai Connectors

This release adds a new Streamable HTTP transport server that enables the Kimai MCP server to work as a remote connector in Claude.ai, allowing access from web and mobile clients.

Key Features

• Multi-user support: Each user gets their own endpoint (/mcp/{user_slug})
• Server-side credentials: Kimai tokens stored securely in users.json config
• Claude.ai compatible: Works with Claude.ai Connectors (Settings > Connectors > Add custom connector)
• No OAuth required: Simple URL-based access without complex authentication flows

New Files

• streamable_http_server.py - Main Streamable HTTP server implementation
• user_config.py - User configuration management
• config/users.example.json - Example configuration template

Usage

1. Copy and configure config/users.example.json to config/users.json
2. Start the server:

   # Local
   kimai-mcp-streamable --users-config=./config/users.json
   
   # Docker
   docker-compose up -d

3. Add connector in Claude.ai: https://your-domain.com/mcp/{username}

Endpoints

• GET / - Server info
• GET /health - Health check
• GET /users - List available user endpoints
• GET/POST/DELETE /mcp/{user_slug} - MCP endpoint per user

Breaking Changes

• Default Docker command changed from kimai-mcp-server to kimai-mcp-streamable
• Docker compose now requires config/users.json volume mount

To use the legacy SSE server, override the Docker command:

command: ["kimai-mcp-server"]

v2.7.1

Fixes

• Remove unused imports and variables in sse_server.py (CI linting fix)

Changes

• asyncio import removed
• typing.Any import removed
• EventSourceResponse import removed
• Unused exception variable e removed
• Unused message variable replaced with _

v2.7.0

What's New in v2.7.0

Added

• Remote MCP Server with HTTP/SSE Transport - New sse_server.py enables remote deployment of the MCP server, allowing multiple clients to connect via HTTP/SSE
• Per-Client Kimai Authentication - Each client can now use their own Kimai credentials when connecting to the remote server
• Docker Support - Complete Docker deployment with multi-architecture images (amd64/arm64)
  • New Dockerfile for containerized deployment
  • New docker-compose.yml for easy orchestration
  • GitHub Actions workflow for automatic Docker image publishing to GHCR
• Deployment Documentation - Comprehensive guide in DEPLOYMENT.md for remote server setup
• Release Process Documentation - Step-by-step release guide in RELEASING.md
• New CLI entry point kimai-mcp-server for running the SSE server

Changed

• Added [server] optional dependencies in pyproject.toml for FastAPI, Uvicorn, and SSE-Starlette

Installation

# Via pip
pip install kimai-mcp

# Via Docker
docker pull ghcr.io/glazperle/kimai_mcp:2.7.0

Full Changelog: v2.6.0...v2.7.0

v2.6.0 - Batch Operations

New Feature: Batch Operations

Enables parallel execution of multiple API calls using asyncio.gather() for efficient bulk operations. Rate limited to max 10 concurrent requests to avoid overloading the Kimai API.

New Actions

Tool	Action	Description
absence	batch_delete	Delete multiple absences at once
absence	batch_approve	Approve multiple absence requests
absence	batch_reject	Reject multiple absence requests
timesheet	batch_delete	Delete multiple timesheets
timesheet	batch_export	Mark multiple timesheets as exported
entity	batch_delete	Delete multiple entities (projects, activities, customers, teams, tags, holidays)

Example Usage

{
  "action": "batch_delete",
  "ids": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
}

Example Output

Batch Delete Complete
✓ Deleted: 8 absences
✗ Failed: 2
  - ID 5: Permission denied
  - ID 9: Not found

---

🤖 Generated with Claude Code

v2.5.3 - Auto-split 30-day limit

New Feature

Automatic 30-Day Splitting

Kimai limits absences to a maximum of 30 days per entry. The MCP now automatically splits longer absences into 30-day chunks.

This works in combination with the existing year-boundary splitting (v2.5.1).

Example: 90 days parental leave

{
  "action": "create",
  "data": {
    "date": "2025-09-01",
    "end": "2025-11-29",
    "type": "parental",
    "comment": "Elternzeit"
  }
}

Automatically becomes:

1. 2025-09-01 to 2025-09-30 (30 days)
2. 2025-10-01 to 2025-10-30 (30 days)
3. 2025-10-31 to 2025-11-29 (30 days)

Output:

Created 3 absence(s) for parental
Period: 2025-09-01 to 2025-11-29 (90 days)
IDs: 123, 124, 125
(Automatically split due to Kimai limitations)

---

🤖 Generated with Claude Code