How do I use kimai-mcp-server?

1. Click on "Deploy 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 Source Related Servers Discussions Admin

TypeScript

Remote

Kimai MCP Server

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

Quick start

Claude

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

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

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: mcp-timely

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.

Available Tools

28 tools

kimai_create_timesheetCreate Kimai TimesheetA

Create a Kimai timesheet record. Sensitive edit: call only after explicit human authorization. The request and created record are saved to a temp backup file.

Inputs: begin (required), project (required), activity (required), authorization_note (required), +11 more.

kimai_duplicate_timesheetDuplicate Kimai TimesheetA

Duplicate an existing Kimai timesheet. Sensitive edit: call only after explicit human authorization. The source and created record are saved to a temp backup file.

Inputs: id (required), authorization_note (required), authorization_confirmed (required), response_format.

kimai_get_activityGet Kimai ActivityA

Read-onlyIdempotent

Read one Kimai activity from /api/activities/. This tool is read-only.

Inputs: id (required), response_format.

kimai_get_current_userGet Current Kimai UserA

Read-onlyIdempotent

Read the current Kimai user from /api/users/me. This tool is read-only.

Inputs: response_format.

kimai_get_customerGet Kimai CustomerA

Read-onlyIdempotent

Read one Kimai customer from /api/customers/. This tool is read-only.

Inputs: id (required), response_format.

kimai_get_expenseGet Kimai ExpenseA

Read-onlyIdempotent

Read one expense from /api/expenses/ when the Kimai expenses feature/plugin is available. This tool is read-only.

Inputs: id (required), response_format.

kimai_get_invoiceGet Kimai InvoiceA

Read-onlyIdempotent

Read one Kimai invoice from /api/invoices/. This tool is read-only.

Inputs: id (required), response_format.

kimai_get_projectGet Kimai ProjectA

Read-onlyIdempotent

Read one Kimai project from /api/projects/. This tool is read-only.

Inputs: id (required), response_format.

kimai_get_server_infoGet Kimai Server InfoA

Read-onlyIdempotent

Read Kimai API status, version, plugin, and timesheet configuration endpoints. This tool is read-only.

Inputs: response_format.

kimai_get_taskGet Kimai TaskA

Read-onlyIdempotent

Read one task from /api/tasks/ when the Kimai tasks feature/plugin is available. This tool is read-only.

Inputs: id (required), response_format.

kimai_get_teamGet Kimai TeamA

Read-onlyIdempotent

Read one Kimai team from /api/teams/. This tool is read-only.

Inputs: id (required), response_format.

kimai_get_timesheetGet Kimai TimesheetA

Read-onlyIdempotent

Read one Kimai timesheet entry from /api/timesheets/. This tool is read-only.

Inputs: id (required), response_format.

kimai_get_userGet Kimai UserB

Read-onlyIdempotent

Read one Kimai user from /api/users/. This tool is read-only.

Inputs: id (required), response_format.

kimai_list_active_timesheetsList Active Kimai TimesheetsA

Read-onlyIdempotent

List currently running Kimai timesheet entries from /api/timesheets/active. This tool is read-only.

Inputs: page, size, response_format.

kimai_list_activitiesList Kimai ActivitiesA

Read-onlyIdempotent

List activities visible to the Kimai API token from /api/activities, optionally filtered by project. This tool is read-only.

Inputs: page, size, term, order, +4 more.

kimai_list_customersList Kimai CustomersA

Read-onlyIdempotent

List customers visible to the Kimai API token from /api/customers. This tool is read-only.

Inputs: page, size, term, order, +3 more.

kimai_list_expensesList Kimai ExpensesB

Read-onlyIdempotent

List expenses from /api/expenses when the Kimai expenses feature/plugin is available. This tool is read-only.

Inputs: page, size, response_format.

kimai_list_invoicesList Kimai InvoicesB

Read-onlyIdempotent

List Kimai invoices from /api/invoices. This tool is read-only.

Inputs: page, size, term, order, +2 more.

kimai_list_projectsList Kimai ProjectsA

Read-onlyIdempotent

List projects visible to the Kimai API token from /api/projects, optionally filtered by customer. This tool is read-only.

Inputs: page, size, term, order, +4 more.

kimai_list_recent_timesheetsList Recent Kimai TimesheetsB

Read-onlyIdempotent

List recent Kimai timesheet entries from /api/timesheets/recent. This tool is read-only.

Inputs: page, size, response_format.

kimai_list_tagsList Kimai TagsB

Read-onlyIdempotent

List Kimai tags from /api/tags/find. This tool is read-only.

Inputs: name, page, size, response_format.

kimai_list_tasksList Kimai TasksB

Read-onlyIdempotent

List tasks from /api/tasks when the Kimai tasks feature/plugin is available. This tool is read-only.

Inputs: page, size, response_format.

kimai_list_teamsList Kimai TeamsA

Read-onlyIdempotent

List Kimai teams from /api/teams. This tool is read-only.

Inputs: page, size, response_format.

kimai_list_timesheetsList Kimai TimesheetsA

Read-onlyIdempotent

List Kimai timesheet entries from /api/timesheets with optional user, customer, project, activity, date, tag, exported, and active filters. This tool is read-only.

Inputs: end, page, size, tags, +8 more.

kimai_list_usersList Kimai UsersB

Read-onlyIdempotent

List Kimai users visible to the API token from /api/users. This tool is read-only.

Inputs: page, size, response_format.

kimai_restart_timesheetRestart Kimai TimesheetA

Restart a stopped Kimai timesheet. Sensitive edit: call only after explicit human authorization. The existing record is saved to a temp backup file before restarting.

Inputs: id (required), authorization_note (required), authorization_confirmed (required), begin, +1 more.

kimai_stop_timesheetStop Kimai TimesheetA

Stop an active Kimai timesheet. Sensitive edit: call only after explicit human authorization. The existing record is saved to a temp backup file before stopping.

Inputs: id (required), authorization_note (required), authorization_confirmed (required), begin, +1 more.

kimai_update_timesheetUpdate Kimai TimesheetA

Update a Kimai timesheet record. Sensitive edit: call only after explicit human authorization. The existing record is saved to a temp backup file before the edit.

Inputs: id (required), authorization_note (required), authorization_confirmed (required), end, +11 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored 2026-07-29 08:40 across 28 tools

Disambiguation5/5

Every tool targets a distinct resource and operation, with clear naming like kimai_list_users vs kimai_get_user. No two tools overlap in purpose, ensuring agents can easily select the correct tool.

Naming Consistency5/5

All tools follow a consistent kimai_{verb}_{noun} pattern in snake_case, such as kimai_list_projects, kimai_get_project, kimai_create_timesheet. This uniformity makes the tool surface predictable.

Tool Count4/5

With 28 tools covering multiple resource types (users, customers, projects, activities, timesheets, invoices, teams, tasks, expenses), the count is slightly high but still well-scoped for a comprehensive Kimai API wrapper. It avoids excessive granularity.

Completeness3/5

The tool set provides robust read-only access and full lifecycle operations for timesheets, but lacks create/update/delete for other entities like customers, projects, and activities. This leaves notable gaps for full CRUD management.

Maintenance

ActivityMaintained

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Timesheet
io.github.timesheetIO
timesheet.io MCP server - manage timers, projects, tasks and reports
Project Management Workplace & Productivity
11
https://mcp.timesheet.io
mcp-server
io.klokin
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Workplace & Productivity Project Management
2
https://mcp.klokin.io
MOCO
com.mocoapp.api
MCP server for MOCO business software: time tracking, projects, budgets, and invoicing via API
Project Management Finance Payments & Billing
1
https://api.mocoapp.com/mcp
cloudtime API
io.github.julysoft
MCP server providing attendance data queries via the CloudTime API.
Workplace & Productivity
2
https://cloudtime-api.zktecoiot.com/api/v1.0/agent/mcp

Related MCP Servers

timesheet-data
Databases File Systems Workplace & Productivity
rodrigo-arias
A
license
Not graded
quality
C
maintenance
MCP server for querying work checkpoints and storing finalized timesheet reports in SQLite.
Updated 3 days ago (2026-11-10 18:47 UTC)
MIT
mcp-timely
Project Management Workplace & Productivity
CaseyRo
A
license
A
quality
B
maintenance
A read-only MCP server for querying Timely time tracking data, providing tools for project overviews, time spent summaries, and work log entries.
Updated 5 days ago (2026-11-09 05:18 UTC)
3
MIT
kimai-task-tracker-mcp
Project Management Workplace & Productivity
byteflowsivar
A
license
A
quality
C
maintenance
MCP server that enables managing tasks (Activities) in a Kimai project and tracking time, with tools to list, create, complete, reopen, start/stop timers, and log time.
Updated 3 months ago (2026-08-03 12:18 UTC)
10
11 npm
MIT
clockify-mcp
Project Management App Automation
apet97
A
license
Not graded
quality
C
maintenance
Read-only MCP server for Clockify time tracking, exposing 60 raw read tools and five workflows for status, workspace overview, and review of days/weeks.
Updated 3 months ago (2026-08-13 17:33 UTC)
MIT

Kimai MCP Server

Quick start

Claude

Cursor

VS Code

Codex

mcp.json

Configuration

Security & write safety

Tools

API coverage

Contributing

License

Copyright

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

timesheet-data

mcp-timely

kimai-task-tracker-mcp

clockify-mcp