@jdlar/kimai-mcp

MCP (Model Context Protocol) server for Kimai time-tracking. Exposes your Kimai instance as 44 tools that any MCP-compatible AI client can use — Claude Desktop, OpenCode, Cursor, etc.

Prerequisites

• Node.js >= 18
• A running Kimai instance with API access
• An API token (generate one in your Kimai user profile under API Access / API Token)

Quick Start

Option 1: NPX (Recommended - No Installation Required)

KIMAI_API_URL=https://your-kimai.example.com KIMAI_API_TOKEN=your-token npx @jdlar/kimai-mcp

Option 2: Global Installation

# 1. Install globally
npm install -g @jdlar/kimai-mcp

# 2. Set environment variables and run
KIMAI_API_URL=https://your-kimai.example.com KIMAI_API_TOKEN=your-token @jdlar/kimai-mcp

Option 3: Environment File

# Create .env file with your credentials
echo "KIMAI_API_URL=https://your-kimai.example.com" > .env
echo "KIMAI_API_TOKEN=your-token" >> .env

# Run with npx
npx @jdlar/kimai-mcp

# Or run with global installation
@jdlar/kimai-mcp

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config file:

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

Option A: Using NPX (Recommended)

{
  "mcpServers": {
    "kimai": {
      "command": "npx",
      "args": ["-y", "@jdlar/kimai-mcp"],
      "env": {
        "KIMAI_API_URL": "https://your-kimai.example.com",
        "KIMAI_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Option B: Using Global Installation

{
  "mcpServers": {
    "kimai": {
      "command": "@jdlar/kimai-mcp",
      "env": {
        "KIMAI_API_URL": "https://your-kimai.example.com",
        "KIMAI_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

OpenCode

Add to your opencode.json:

{
  "mcp": {
    "kimai": {
      "type": "local",
      "command": ["npx", "-y", "@jdlar/kimai-mcp"],
      "env": {
        "KIMAI_API_URL": "https://your-kimai.example.com",
        "KIMAI_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "kimai": {
      "command": "npx",
      "args": ["-y", "@jdlar/kimai-mcp"],
      "env": {
        "KIMAI_API_URL": "https://your-kimai.example.com",
        "KIMAI_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Other MCP Clients

For any MCP-compatible client, configure:

• Command: npx (or @jdlar/kimai-mcp if installed globally)
• Args: ["-y", "@jdlar/kimai-mcp"] (only when using npx)
• Transport: stdio
• Environment variables:
  • KIMAI_API_URL — Your Kimai instance URL (without trailing slash)
  • KIMAI_API_TOKEN — API token from your Kimai user profile

Available Tools

Timesheets (10 tools)

| Tool | Description | |------|-------------| | kimai-list-timesheets | List/filter timesheet entries (by user, project, customer, date range, active state, tags, etc.) | | kimai-get-timesheet | Get a single timesheet by ID | | kimai-create-timesheet | Create a new timesheet entry (start a timer or log completed work) | | kimai-update-timesheet | Update an existing timesheet | | kimai-delete-timesheet | Delete a timesheet entry | | kimai-get-active-timesheets | Get currently running timesheets | | kimai-stop-timesheet | Stop a running timesheet | | kimai-restart-timesheet | Restart a stopped timesheet | | kimai-duplicate-timesheet | Duplicate a timesheet entry | | kimai-get-recent-timesheets | Get recent timesheet entries |

Customers (4 tools)

| Tool | Description | |------|-------------| | kimai-list-customers | List/filter customers | | kimai-get-customer | Get customer by ID | | kimai-create-customer | Create a new customer | | kimai-update-customer | Update an existing customer |

Projects (4 tools)

| Tool | Description | |------|-------------| | kimai-list-projects | List/filter projects | | kimai-get-project | Get project by ID | | kimai-create-project | Create a new project | | kimai-update-project | Update an existing project |

Activities (4 tools)

| Tool | Description | |------|-------------| | kimai-list-activities | List/filter activities | | kimai-get-activity | Get activity by ID | | kimai-create-activity | Create a new activity (project-scoped or global) | | kimai-update-activity | Update an existing activity |

Users (3 tools)

| Tool | Description | |------|-------------| | kimai-list-users | List users (requires view_user permission) | | kimai-get-user | Get user by ID | | kimai-get-me | Get current authenticated user |

Tags (3 tools)

| Tool | Description | |------|-------------| | kimai-list-tags | List/filter tags | | kimai-create-tag | Create a new tag | | kimai-delete-tag | Delete a tag |

Teams (13 tools)

| Tool | Description | |------|-------------| | kimai-list-teams | List all teams | | kimai-get-team | Get team by ID | | kimai-create-team | Create a new team | | kimai-update-team | Update an existing team | | kimai-delete-team | Delete a team | | kimai-add-team-member | Add a user to a team | | kimai-remove-team-member | Remove a user from a team | | kimai-add-team-customer | Grant team access to a customer | | kimai-remove-team-customer | Revoke team access to a customer | | kimai-add-team-project | Grant team access to a project | | kimai-remove-team-project | Revoke team access to a project | | kimai-add-team-activity | Grant team access to an activity | | kimai-remove-team-activity | Revoke team access to an activity |

System (3 tools)

| Tool | Description | |------|-------------| | kimai-ping | Test API connection | | kimai-get-version | Get Kimai version info | | kimai-get-timesheet-config | Get timesheet configuration |

Example Prompts

Once connected, you can ask your AI assistant things like:

Time Tracking

Start a timer on project "Website Redesign", activity "Development"

What timesheets did I log this week?

Stop my running timer

Reporting

Show me all timesheet entries for customer "Acme Corp" in January 2026

How many hours did I track on project "Mobile App" this month?

Management

List all active projects for customer "Acme Corp"

Create a new customer called "NewCo" based in the US with USD currency

Create a project "Q1 Campaign" under the "Marketing Agency" customer

Permissions

All 44 tools are always registered. If your API token lacks a required permission for a specific tool, it returns a clear error message instead of failing silently — for example:

Permission denied (403): Your Kimai API token does not have access to this endpoint.
Check your user role and permissions in Kimai.

No role configuration is needed. Just use the tools and Kimai's permission system handles the rest.

Generating an API Token

1. Log in to your Kimai instance
2. Click on your profile icon (top right)
3. Navigate to API Access or API Token
4. Create a new API token
5. Copy the token and use it as KIMAI_API_TOKEN

The token inherits the permissions of the user who created it. Admin tokens can access all endpoints; regular user tokens are scoped to their own data.

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

# Run the server
pnpm start

License

MIT