@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)

Customers (4 tools)

Projects (4 tools)

Activities (4 tools)

Users (3 tools)

Tags (3 tools)

Teams (13 tools)

System (3 tools)

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