kimai-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server for KIMAI 2, a time tracking application. It exposes 20+ tools that enable LLMs to interact with KIMAI for time tracking, project management, and reporting through the KIMAI REST API.

Technology Stack:

• Python 3.10+ with asyncio
• MCP SDK (mcp>=1.0.0) for protocol implementation
• httpx for async HTTP requests
• Pydantic v2 for input validation and schema generation

Development Commands

Setup and Installation

# Initial setup (creates venv, installs dependencies, creates .env)
./setup.sh

# Manual setup
uv venv
uv pip install -r requirements.txt
cp .env.example .env
# Edit .env with your KIMAI_BASE_URL and KIMAI_API_TOKEN

Testing

# Test KIMAI API connection
source .venv/bin/activate
python test_connection.py

# Run the MCP server directly (waits for stdio input)
python server.py

Environment Configuration

Required environment variables (set in .env or MCP client config):

• KIMAI_BASE_URL: Base URL of KIMAI instance (e.g., http://localhost:8001)
• KIMAI_API_TOKEN: Bearer token from KIMAI User Profile > API

Architecture

Core Components

server.py (1566 lines) - Single-file MCP server with clear sections:

1. Pydantic Models (lines ~35-550): Input validation models for all 20+ tools

   • Each tool has a dedicated model with strict validation
   • All models use ConfigDict(extra='forbid') to reject unknown fields
   • Field-level validation with descriptions for LLM schema generation

2. KimaiClient (lines ~570-660): HTTP client wrapper

   • Async request method handles all HTTP operations
   • Bearer token authentication via headers
   • Comprehensive error handling with actionable messages
   • Base URL joining for API endpoints

3. Response Formatters (lines ~665-845): Markdown and JSON output

   • Functions like format_timesheet_markdown(), format_project_markdown()
   • truncate_if_needed() caps output at 25000 characters
   • Supports both human-readable markdown and structured JSON