Kimai MCP Server

A comprehensive Model Context Protocol (MCP) server for integrating with the Kimai time-tracking API. This server allows AI assistants like Claude to efficiently interact with Kimai instances to manage time tracking, projects, activities, customers, users, teams, absences, and more.

🚀 Quick Start

Local Installation (Single User)

# Install from PyPI
pip install kimai-mcp

# Run with your Kimai credentials
kimai-mcp --kimai-url=https://your-kimai.com --kimai-token=your-token

# Or use the interactive setup wizard
kimai-mcp --setup

🌐 Remote Server Deployment (Recommended for Teams)

For enterprise/team environments: Deploy the server once and let all users connect remotely!

Server Types

Quick Start with Docker (Streamable HTTP)

# 1. Generate a random slug for security (DO NOT use usernames!)
python -c "import secrets; print(secrets.token_urlsafe(12))"
# Output example: xK9mP2qW7vL4

# 2. Create config file with random slug
mkdir config
cat > config/users.json << 'EOF'
{
  "xK9mP2qW7vL4": {
    "kimai_url": "https://your-kimai.com",
    "kimai_token": "your-api-token",
    "kimai_user_id": "1"
  }
}
EOF

# 3. Start server
docker-compose up -d

Security Warning: Use random slugs, NOT usernames! Predictable URLs like /mcp/john can be easily guessed. Generate secure slugs with python -c "import secrets; print(secrets.token_urlsafe(12))"

Claude.ai Connectors Integration

The Streamable HTTP server works with Claude.ai custom connectors:

1. Deploy server with Docker (see above)
2. In Claude.ai: Settings → Connectors → Add custom connector
3. Enter URL: https://your-domain.com/mcp/xK9mP2qW7vL4 (your random slug)
4. Done! Works in Claude.ai web and mobile apps

Benefits:

• ✅ Works with Claude.ai web and mobile apps
• ✅ Each user gets their own endpoint (/mcp/{random-slug})
• ✅ Server-side credential management
• ✅ No client-side token exposure

Claude Desktop (SSE Server)

For Claude Desktop with remote server access:

{
  "mcpServers": {
    "kimai": {
      "url": "http://your-server:8000/sse",
      "headers": {
        "Authorization": "Bearer MCP-SERVER-TOKEN",
        "X-Kimai-Token": "YOUR-PERSONAL-KIMAI-TOKEN"
      }
    }
  }
}

📖 See full deployment guide →

Command Line Options

🛠️ Available Tools

Core Management Tools

1. Entity Tool - Universal CRUD operations for projects, activities, customers, users, teams, tags, invoices, holidays
2. Timesheet Tool - Complete timesheet management (list, create, update, delete, export, batch operations)
3. Timer Tool - Active timer operations (start, stop, restart, view active/recent)
4. Rate Tool - Rate manage

... View full README on GitHub