How do I use kimai-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kimai-mcp-server show my recent timesheets" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

kimai-mcp-server

by NightSquawk

Overview Schema Related Servers Score Discussions

TypeScript

Remote

Kimai MCP Server

npm version npm downloads OpenSSF Scorecard License: AGPL-3.0 Node

An MCP (Model Context Protocol) server for Kimai, connecting your self-hosted time tracking to AI tools.

Quick start

Claude

Download for Claude Desktop

bash (macOS/Linux):

KIMAI_BASE_URL="https://example.kimai.cloud"
KIMAI_API_TOKEN="replace-with-api-token"

claude mcp add kimai \
  --env KIMAI_BASE_URL="$KIMAI_BASE_URL" \
  --env KIMAI_API_TOKEN="$KIMAI_API_TOKEN" \
  -- npx -y @nightsquawktech/kimai-mcp-server

PowerShell (Windows):

$KIMAI_BASE_URL = "https://example.kimai.cloud"
$KIMAI_API_TOKEN = "replace-with-api-token"

claude mcp add kimai `
  --env "KIMAI_BASE_URL=$KIMAI_BASE_URL" `
  --env "KIMAI_API_TOKEN=$KIMAI_API_TOKEN" `
  -- npx -y @nightsquawktech/kimai-mcp-server

Cursor

Add to Cursor

Or put the mcp.json block in .cursor/mcp.json, then verify with:

agent mcp list

(The Cursor CLI manages configured servers but has no mcp add; install is via the button or mcp.json.)

VS Code

Install in VS Code

bash (macOS/Linux):

KIMAI_BASE_URL="https://example.kimai.cloud"
KIMAI_API_TOKEN="replace-with-api-token"

code --add-mcp '{"name":"kimai","command":"npx","args":["-y","@nightsquawktech/kimai-mcp-server"],"env":{"KIMAI_BASE_URL":"'"$KIMAI_BASE_URL"'","KIMAI_API_TOKEN":"'"$KIMAI_API_TOKEN"'"}}'

PowerShell (Windows):

$KIMAI_BASE_URL = "https://example.kimai.cloud"
$KIMAI_API_TOKEN = "replace-with-api-token"

$config = @{
  name = "kimai"
  command = "npx"
  args = @("-y", "@nightsquawktech/kimai-mcp-server")
  env = @{
    KIMAI_BASE_URL = $KIMAI_BASE_URL
    KIMAI_API_TOKEN = $KIMAI_API_TOKEN
  }
} | ConvertTo-Json -Compress

code --add-mcp $config

Codex

bash (macOS/Linux):

KIMAI_BASE_URL="https://example.kimai.cloud"
KIMAI_API_TOKEN="replace-with-api-token"

codex mcp add kimai \
  --env KIMAI_BASE_URL="$KIMAI_BASE_URL" \
  --env KIMAI_API_TOKEN="$KIMAI_API_TOKEN" \
  -- npx -y @nightsquawktech/kimai-mcp-server

PowerShell (Windows):

$KIMAI_BASE_URL = "https://example.kimai.cloud"
$KIMAI_API_TOKEN = "replace-with-api-token"

codex mcp add kimai `
  --env "KIMAI_BASE_URL=$KIMAI_BASE_URL" `
  --env "KIMAI_API_TOKEN=$KIMAI_API_TOKEN" `
  -- npx -y @nightsquawktech/kimai-mcp-server

Or add it to ~/.codex/config.toml under [mcp_servers.kimai].

mcp.json

Every environment variable the server reads, with recommended values:

{
  "mcpServers": {
    "kimai": {
      "command": "npx",
      "args": ["-y", "@nightsquawktech/kimai-mcp-server"],
      "env": {
        "KIMAI_BASE_URL": "https://example.kimai.cloud",
        "KIMAI_API_TOKEN": "replace-with-api-token",
        "KIMAI_TIMEOUT_MS": "30000"
      }
    }
  }
}

File locations: .mcp.json in your project root (Claude Code), claude_desktop_config.json (Claude Desktop), .cursor/mcp.json (Cursor).

Related MCP server: timedoctor-mcp

Configuration

Variable	Required	Default	Purpose
`KIMAI_BASE_URL`	yes		Your Kimai URL without a trailing slash, e.g. `https://example.kimai.cloud`
`KIMAI_API_TOKEN`	yes		API token generated in your Kimai user profile (API Access)
`KIMAI_TIMEOUT_MS`	no	`30000`	HTTP timeout for Kimai API requests, minimum 1000

Security & write safety

Kimai credentials: generate an API token in your Kimai user profile. The token inherits that user's permissions, so use a dedicated Kimai user with the smallest role that covers what you need.

23 of the 28 tools are read-only. They only issue GET requests and cannot change anything in Kimai.
5 timesheet write tools exist: kimai_create_timesheet, kimai_update_timesheet, kimai_stop_timesheet, kimai_restart_timesheet, kimai_duplicate_timesheet. There is no env gate; each call is guarded instead:
- Every write requires authorization_confirmed: true and an authorization_note (8+ characters) recording the user's explicit approval. The tool descriptions instruct the model to call them only after a human authorizes the edit.
- Every write saves a JSON backup (previous record, request, and result) to kimai-mcp-backups in the OS temp directory, so edits can be audited and manually reverted.
No delete tools are exposed.
All requests go directly from your machine to your Kimai instance; nothing passes through third parties.

IMPORTANT

The authorization fields are a guardrail, not a security boundary. The env vars in your MCP config are real credentials, and an AI agent with shell access can bypass the MCP tools and call the Kimai API directly with them. If you need hard read-only, enforce it at the source: give the token's Kimai user a role without timesheet edit permissions.

Tools

kimai_get_server_info           Kimai version, plugins, and timesheet config
kimai_get_current_user          The user behind the API token
kimai_list_users                List users
kimai_get_user                  Get one user
kimai_list_customers            List customers
kimai_get_customer              Get one customer
kimai_list_projects             List projects, optionally filtered by customer
kimai_get_project               Get one project
kimai_list_activities           List activities, optionally filtered by project
kimai_get_activity              Get one activity
kimai_list_tags                 Find tags by name
kimai_list_timesheets           List timesheets with user/customer/project/date/tag filters
kimai_get_timesheet             Get one timesheet entry
kimai_list_active_timesheets    Currently running timesheets
kimai_list_recent_timesheets    Recent timesheet entries
kimai_create_timesheet          Create a timesheet entry (write, requires authorization fields)
kimai_update_timesheet          Update a timesheet entry (write, requires authorization fields)
kimai_stop_timesheet            Stop a running timesheet (write, requires authorization fields)
kimai_restart_timesheet         Restart a stopped timesheet (write, requires authorization fields)
kimai_duplicate_timesheet       Duplicate a timesheet entry (write, requires authorization fields)
kimai_list_teams                List teams
kimai_get_team                  Get one team
kimai_list_invoices             List invoices
kimai_get_invoice               Get one invoice
kimai_list_expenses             List expenses (expenses plugin)
kimai_get_expense               Get one expense (expenses plugin)
kimai_list_tasks                List tasks (tasks plugin)
kimai_get_task                  Get one task (tasks plugin)

API coverage

31 operations covered across 28 tools.

Category	Operations
Server & status	4
Users	3
Customers, projects, activities, tags	7
Timesheets (read)	4
Timesheets (write)	5
Teams & invoices	4
Plugins: expenses & tasks	4

Method	Path	Tool
GET	`/api/ping`	`kimai_get_server_info`
GET	`/api/version`	`kimai_get_server_info`
GET	`/api/plugins`	`kimai_get_server_info`
GET	`/api/config/timesheet`	`kimai_get_server_info`

Method	Path	Tool
GET	`/api/users/me`	`kimai_get_current_user`
GET	`/api/users`	`kimai_list_users`
GET	`/api/users/{id}`	`kimai_get_user`

Method	Path	Tool
GET	`/api/customers`	`kimai_list_customers`
GET	`/api/customers/{id}`	`kimai_get_customer`
GET	`/api/projects`	`kimai_list_projects`
GET	`/api/projects/{id}`	`kimai_get_project`
GET	`/api/activities`	`kimai_list_activities`
GET	`/api/activities/{id}`	`kimai_get_activity`
GET	`/api/tags/find`	`kimai_list_tags`

Method	Path	Tool
GET	`/api/timesheets`	`kimai_list_timesheets`
GET	`/api/timesheets/{id}`	`kimai_get_timesheet`
GET	`/api/timesheets/active`	`kimai_list_active_timesheets`
GET	`/api/timesheets/recent`	`kimai_list_recent_timesheets`

Method	Path	Tool
POST	`/api/timesheets`	`kimai_create_timesheet`
PATCH	`/api/timesheets/{id}`	`kimai_update_timesheet`
PATCH	`/api/timesheets/{id}/stop`	`kimai_stop_timesheet`
PATCH	`/api/timesheets/{id}/restart`	`kimai_restart_timesheet`
PATCH	`/api/timesheets/{id}/duplicate`	`kimai_duplicate_timesheet`

Method	Path	Tool
GET	`/api/teams`	`kimai_list_teams`
GET	`/api/teams/{id}`	`kimai_get_team`
GET	`/api/invoices`	`kimai_list_invoices`
GET	`/api/invoices/{id}`	`kimai_get_invoice`

Method	Path	Tool
GET	`/api/expenses`	`kimai_list_expenses`
GET	`/api/expenses/{id}`	`kimai_get_expense`
GET	`/api/tasks`	`kimai_list_tasks`
GET	`/api/tasks/{id}`	`kimai_get_task`

Contributing

Contributions and issues are welcome. Please open an issue first before submitting a PR.

License

AGPL-3.0: free for personal and open-source use. Organizations that cannot comply with the AGPL can purchase a commercial license, and hosted/managed versions are available. See COMMERCIAL.md or contact hello@nightsquawk.tech.

Copyright

For copyright concerns or takedown requests, contact hello@nightsquawk.tech.

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

1Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/NightSquawk/kimai-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server