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.

Development Commands

Install Dependencies

# Install package in development mode
pip install -e .

# Install with dev dependencies for testing and linting
pip install -e ".[dev]"

Testing

# Run all tests
pytest tests/ -v

# Run specific test file (available: test_oauth.py, test_security.py, test_timesheet_list.py)
pytest tests/test_oauth.py -v

# Run with coverage (if pytest-cov installed)
pytest tests/ -v --cov=kimai_mcp

Code Formatting and Linting

# Format code with black
black src/ tests/

# Run linting with ruff
ruff check src/ tests/

# Fix linting issues automatically
ruff check --fix src/ tests/

Running the Server

There are two server types:

# 1. LOCAL MCP SERVER (for Claude Desktop)
python -m kimai_mcp --kimai-url=https://your-kimai.com --kimai-token=your-token
# or: kimai-mcp --kimai-url=... --kimai-token=...

# 2. STREAMABLE HTTP SERVER (for Claude.ai Connectors, OAuth 2.1 since v2.12.0)
python -m kimai_mcp.streamable_http_server --users-config=./config/users.json
# or: kimai-mcp-streamable --users-config=./config/users.json
# Production (behind HTTPS reverse proxy):
kimai-mcp-streamable --users-config ./config/users.json \
  --public-url https://mcp.example.com --trusted-proxy 127.0.0.1 \
  --oauth-state-file ./config/oauth_clients.json --disable-legacy-slugs

Server	Command	Protocol	Use Case
Local	kimai-mcp	MCP Stdio	Claude Desktop local
Streamable	kimai-mcp-streamable	HTTP Streamable + OAuth 2.1	Claude.ai Connectors

Notes:

• The SSE server (sse_server.py, command kimai-mcp-server) was removed in v2.16.0. It had been non-functional since v2.12.0 (broken transport wiring, and the SSE transport is no longer part of the MCP specification). The SDK still ships mcp.server.sse, so this was dead code in this project, not a forced removal.
• --kimai-user / KIMAI_DEFAULT_USER is deprecated: accepted but ignored (warning is logged). Use the user_scope parameter of the tools instead.
• The streamable server serves an OAuth-protected /mcp endpoint (DCR + PKCE, login form at /oauth/login with user slug + auth_secret). The legacy /mcp/{slug} endpoints still work but are deprecated and can be disabled with --disable-legacy-slugs.
• users.json schema (see src/kimai_mcp/user_config.py): per slug kimai_url, kimai_token, optional ssl_verify, optional auth_secret (env override: KIMAI_USER_<SLUG>_AUTH_SECRET), optional oidc_identity. Slugs must match ^[a-zA-Z0-9_-]+$; keys starting with _ are comments. The former kimai_user_id field was removed and is ignored when present. With --auto-provision, users that are not in this file are added at runtime and exist only in memory unless --provision-store is set.