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.

Speaks MCP protocol revision 2026-07-28 and every earlier revision (MCP Python SDK 2.x), tracked against Kimai 2.66. Older Kimai instances keep working; features that need a specific Kimai version are marked below.

🚀 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

Removed in v2.16.0: the SSE server and its kimai-mcp-server command are gone. The SSE transport was dropped from the MCP specification in favour of Streamable HTTP, and this project's implementation had been non-functional and deprecated since v2.12.0. Use kimai-mcp-streamable for remote access.

Quick Start with Docker (Streamable HTTP + OAuth)

Since v2.12.0 the Streamable HTTP server includes an OAuth 2.1 authorization server. Users authenticate with a user slug and a per-user auth_secret instead of a secret URL.

# 1. Generate a random slug and an auth_secret per user
python -c "import secrets; print(secrets.token_urlsafe(16))"   # slug
python -c "import secrets; print(secrets.token_urlsafe(32))"   # auth_secret

# 2. Create config file
mkdir config
cat > config/users.json << 'EOF'
{
  "xK9mP2qW7vL4aB8c": {
    "kimai_url": "https://your-kimai.com",
    "kimai_token": "your-api-token",
    "auth_secret": "long-random-oauth-login-secret"
  }
}
EOF

# 3. Start server
docker-compose up -d

Security Warning: Use random slugs, NOT usernames! The server warns at startup about low-entropy slugs (shorter than 16 characters or plain lowercase words). Slugs may only contain letters, digits, - and _.

Claude.ai Connectors Integration (OAuth)

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

1. Set an auth_secret for each user in users.json (see above)
2. Run the server behind an 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
   

3. In Claude.ai: Settings → Connectors → Add custom connector
4. Enter URL: https://mcp.example.com/mcp (no slug in the URL)
5. Claude.ai registers itself automatically (Dynamic Client Registration). When connecting, a login page appears — enter your user slug and auth_secret.

Access tokens are valid for 1 hour and refreshed automatically (refresh tokens up to 30 days). Tokens are kept in memory, so users must reconnect after a server restart.

Legacy endpoints: The previous per-user URLs /mcp/{slug} still work but are deprecated. Migrate to the OAuth endpoint /mcp and start the server with --disable-legacy-slugs.

OI

... View full README on GitHub