KIMAI MCP Server

A Model Context Protocol (MCP) server for KIMAI 2 time tracking application. This server enables Large Language Models to interact with KIMAI for time tracking, project management, and reporting.

Features

Time Tracking

• Start/Stop Time Entries: Begin and end time tracking in real-time
• Create Time Entries: Add historical time entries with custom start/end times
• Update Time Entries: Modify existing entries (times, descriptions, tags)
• Delete Time Entries: Remove incorrect or duplicate entries
• Query Time Entries: Search and filter timesheets by project, activity, customer, user, date range, and status

Project & Activity Management

• List Projects & Activities: Browse available projects and activities
• Create Projects: Set up new projects under customers
• Create Activities: Define new work types (global or project-specific)
• Update Projects & Activities: Modify names, visibility, billable status, and colors

Customer Management

• List Customers: View all customers
• Create Customers: Add new clients with currency preferences
• Update Customers: Modify customer information and settings

Reporting & Analytics

• Timesheet Summaries: Generate reports with total hours, billable vs non-billable time
• Project Breakdowns: See time distribution across projects
• Activity Analysis: Analyze time spent on different activity types
• Flexible Filtering: Filter reports by user, customer, project, activity, and date range

Prerequisites

• KIMAI 2: A running KIMAI 2 instance (version 2.0 or higher)
• Python: Python 3.10 or higher
• API Token: Bearer token from your KIMAI user profile

Installation

Quick Setup (Recommended)

1. Clone or download this repository:

   cd /projects/personal/kimai-mcp
   

2. Run the setup script:

   ./setup.sh
   

3. Edit .env file with your KIMAI credentials:

   nano .env  # or use your preferred editor
   

4. Test the connection:

   source .venv/bin/activate
   python3 test_connection.py
   

Manual Setup

1. Install dependencies using uv:

   uv venv
   uv pip install -r requirements.txt
   

2. Configure environment variables:

   cp .env.example .env
   # Edit .env with your KIMAI URL and API token
   

Generate KIMAI API Token

• Log into your KIMAI instance
• Navigate to: User Profile > API
• Click "Create New Token"
• Copy the token and add it to your .env file

Configuration

Environment Variables

The server requires two environment variables:

Variable	Description	Example
KIMAI_BASE_URL	Base URL of your KIMAI instance	http://localhost:8001
KIMAI_API_TOKEN	Bearer token for API authentication	<token_here>

Claude Code Configuration

To use this MCP server with Claude Code (CLI), add it to your MCP settings file.

Location: ~/.claude/mcp_settings.json or your project's .claude/mcp_settings.json

Add the following configuration:

{
  "mcpServers": {
    "kimai": {
      "command": "/projects/personal/kimai-mcp/.venv/bin/python",
      "args": ["/projects/personal/kimai-mcp/server.py"],
      "env": {
        "KIMAI_BASE_URL": "http://localhost:8001",
        "KIMAI_API_TOKEN": "<your_api_token_here>"
      }
    }
  }
}

Important Notes:

• Use absolute paths for both command and args
• Replace /projects/personal/kimai-mcp with your actual installation path
• Replace <your_api_token_here> with your KIMAI API token
• The Python binary should point to your virtual environment

After adding the configuration, restart Claude Code to load the MCP server. You can verify it's loaded by checking for KIMAI-related tools.

Claude Desktop Configuration

Add this MCP server to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
	"kimai": {
	  "command": "/projects/personal/kimai-mcp/.venv/bin/python",
	  "args": ["/projects/personal/kimai-mcp/server.py"],
	  "env": {
		"KIMAI_BASE_URL": "http://localhost:8001",
		"KIMAI_API_TOKEN": "your_api_token_here"
	  }
	}
  }
}

Note: Make sure to use absolute paths and point to the Python binary in your virtual environment.

Available Tools

Timesheet Tools

list_timesheets

List timesheet entries with filtering options.

Parameters:

• user (optional): Filter by user ID
• customer (optional): Filter by customer ID
• project (optional): Filter by project ID
• activity (optional): Filter by activity ID
• active (optional): Filter for running timesheets only
• exported (optional): Filter by export status
• begin (optional): Start date filter (ISO 8601)
• end (optional): End date filter (ISO 8601)
• page (default: 1): Page number for pagination
• size (default: 50): Results per page (max 100)
• format (default: "json"): Response format ("json" or "markdown")

Example:

List all running timesheets
Show me timesheets for project 1 from last week

get_timesheet

Get detailed information about a specific timesheet.

Parameters:

• id: Timesheet ID (required)
• format: Response format ("json" or "markdown")

Example:

Get details for timesheet #1245

start_timesheet

Start tracking time for a project and activity.

Parameters:

• project: Project ID (required)
• activity: Activity ID (required)
• description (optional): Work description
• tags (optional): Comma-separated tags

Example:

Start tracking time for project 1, activity 355
Start timer for "Code Review" on project 2

stop_timesheet

Stop a running timesheet entry.

Parameters:

• id: Timesheet ID to stop (required)

Example:

Stop timesheet #1245

create_timesheet

Create a time entry with specific start/end times.

Parameters:

• project: Project ID (required)
• activity: Activity ID (required)
• begin: Start datetime in ISO 8601 format (required)
• end (optional): End datetime (omit for running entry)
• description (optional): Work description
• tags (optional): Comma-separated tags

Example:

Create a timesheet for yesterday from 9am to 5pm on project 1, activity 355
Log 3 hours of work for project 2, activity 10

update_timesheet

Update an existing timesheet entry.

Parameters:

• id: Timesheet ID (required)
• begin (optional): New start datetime
• end (optional): New end datetime
• description (optional): Updated description
• tags (optional): Updated tags

Example:

Update timesheet #1245 with description "Fixed bug in authentication"
Change the end time of timesheet #1244 to 6pm

delete_timesheet

Delete a timesheet entry.

Parameters:

• id: Timesheet ID (required)

Example:

Delete timesheet #1245

Project Tools

list_projects

List all projects with filtering.

Parameters:

• customer (optional): Filter by customer ID
• visible (optional): Filter by visibility
• page (default: 1): Page number
• size (default: 50): Results per page
• format (default: "json"): Response format

Example:

List all projects
Show me projects for customer 1

get_project

Get details about a specific project.

Parameters:

• id: Project ID (required)
• format: Response format

Example:

Get details for project #1

create_project

Create a new project.

Parameters:

• name: Project name (required)
• customer: Customer ID (required)
• visible (default: true): Visibility
• billable (default: true): Billable status
• color (optional): Hex color code

Example:

Create a new project "Website Redesign" for customer 1

update_project

Update a project's details.

Parameters:

• id: Project ID (required)
• name (optional): New name
• visible (optional): New visibility
• billable (optional): New billable status
• color (optional): New color

Example:

Rename project #1 to "Mobile App Development"
Make project #2 non-billable

Activity Tools

list_activities

List all activities.

Parameters:

• project (optional): Filter by project ID
• visible (optional): Filter by visibility
• page (default: 1): Page number
• size (default: 50): Results per page
• format (default: "json"): Response format

Example:

List all activities
Show activities for project 1

get_activity

Get details about a specific activity.

Parameters:

• id: Activity ID (required)
• format: Response format

Example:

Get details for activity #355

create_activity

Create a new activity.

Parameters:

• name: Activity name (required)
• project (optional): Project ID (omit for global)
• visible (default: true): Visibility
• billable (default: true): Billable status
• color (optional): Hex color code

Example:

Create a new activity called "Code Review"
Create a global activity "Meeting"

update_activity

Update an activity's details.

Parameters:

• id: Activity ID (required)
• name (optional): New name
• visible (optional): New visibility
• billable (optional): New billable status
• color (optional): New color

Example:

Rename activity #355 to "Senior Code Review"

Customer Tools

list_customers

List all customers.

Parameters:

• visible (optional): Filter by visibility
• page (default: 1): Page number
• size (default: 50): Results per page
• format (default: "json"): Response format

Example:

List all customers

get_customer

Get details about a specific customer.

Parameters:

• id: Customer ID (required)
• format: Response format

Example:

Get details for customer #1

create_customer

Create a new customer.

Parameters:

• name: Customer name (required)
• currency (default: "USD"): 3-letter currency code
• visible (default: true): Visibility
• billable (default: true): Billable status
• color (optional): Hex color code

Example:

Create a new customer "Acme Corporation" with EUR currency

update_customer

Update a customer's details.

Parameters:

• id: Customer ID (required)
• name (optional): New name
• currency (optional): New currency
• visible (optional): New visibility
• billable (optional): New billable status
• color (optional): New color

Example:

Change customer #1 currency to CAD

Reporting Tools

get_timesheet_summary

Generate summary reports of timesheet data.

Parameters:

• user (optional): Filter by user ID
• customer (optional): Filter by customer ID
• project (optional): Filter by project ID
• activity (optional): Filter by activity ID
• begin (optional): Start date (ISO 8601)
• end (optional): End date (ISO 8601)
• format (default: "markdown"): Response format

Example:

Generate a timesheet report for this week
Show me total hours for project 1 this month
Summary of all billable hours for customer 1

Usage Examples

Time Tracking Workflow

User: Start tracking time for the FNLR project
Claude: [Uses list_projects to find "First Nations Land Register"]
        [Uses list_activities to find appropriate activity]
        [Uses start_timesheet with project=1, activity=355]

User: Stop the timer
Claude: [Uses list_timesheets with active=true to find running entry]
        [Uses stop_timesheet with the ID]

User: Add a description "Implemented authentication feature"
Claude: [Uses update_timesheet to add description]

Reporting Workflow

User: How much time did I spend on project 1 this week?
Claude: [Uses get_timesheet_summary with project=1, date filters]
        [Returns markdown report with breakdown]

User: Show me all my timesheets from yesterday
Claude: [Uses list_timesheets with date filters, format=markdown]
        [Returns formatted list of entries]

Project Setup Workflow

User: Create a new customer "Acme Corp" and project "Website Redesign"
Claude: [Uses create_customer with name="Acme Corp"]
        [Uses create_project with the new customer ID]
        [Uses create_activity for common tasks]

User: What activities are available for this project?
Claude: [Uses list_activities with the new project ID]

Response Formats

The server supports two response formats:

JSON Format

Structured data ideal for programmatic processing:

{
  "id": 1245,
  "project": 1,
  "activity": 355,
  "begin": "2025-11-05T15:36:00+0100",
  "end": "2025-11-05T18:10:00+0100",
  "duration": 9240
}

Markdown Format

Human-readable format ideal for reports and summaries:

## Timesheet #1245

**Status:** ✓ Completed
**Project ID:** 1
**Activity ID:** 355
**Duration:** 2.57 hours (9240 seconds)

Error Handling

The server provides clear, actionable error messages:

• Authentication errors: Check your API token
• Not found errors: Verify IDs exist
• Validation errors: Review parameter formats
• Network errors: Verify KIMAI URL is accessible

All errors include suggestions for resolution.

Development

Testing the Server

# Set environment variables
export KIMAI_BASE_URL=http://localhost:8001
export KIMAI_API_TOKEN=your_token

# Run the server directly (will wait for stdio input)
python server.py

Project Structure

kimai-mcp/
├── server.py           # Main MCP server implementation
├── requirements.txt    # Python dependencies
├── .env.example       # Environment variable template
└── README.md          # This file

Troubleshooting

Server won't start

• Check Python version (3.10+ required)
• Verify all dependencies are installed: pip install -r requirements.txt
• Ensure environment variables are set

API errors

• Verify KIMAI instance is running and accessible
• Check API token is valid (not expired)
• Ensure token has appropriate permissions

Empty results

• Check filters are not too restrictive
• Verify data exists in KIMAI
• Try without filters first

Contributing

Contributions are welcome! Please ensure:

• Code follows Python best practices
• Pydantic models validate all inputs
• Error messages are clear and actionable
• Documentation is updated

License

This project is open source and available under the MIT License.

Support

For issues or questions:

• KIMAI documentation: https://www.kimai.org/documentation/
• MCP documentation: https://modelcontextprotocol.io/

Changelog

v1.0.0 (2025-11-06)

• Initial release
• Full timesheet management (CRUD operations)
• Project, activity, and customer management
• Summary reporting and analytics
• Support for JSON and Markdown response formats
• Comprehensive error handling