Can I use Kimai as a CLI?

Yes. KosmoKrator exposes a Kimai CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Kimai through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Kimai tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Kimai credentials stored?

Kimai credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Kimai MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Kimai CLI for AI Agents

Use the Kimai CLI from KosmoKrator to call Kimai tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

7 functions 6 read 1 write Bearer token auth

Submit Kimai feedback View package source

Kimai CLI Setup

Kimai can be configured headlessly with `kosmokrator integrations:configure kimai`.

# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure kimai --set access_token="$KIMAI_ACCESS_TOKEN" --set url="$KIMAI_URL" --enable --read allow --write ask --json
kosmokrator integrations:doctor kimai --json
kosmokrator integrations:status --json

Credentials

Authentication type: Bearer token bearer_token. Configure credentials once, then use the same stored profile from scripts, coding CLIs, Lua code mode, and the MCP gateway.

Key	Env var	Type	Required	Label
`access_token`	`KIMAI_ACCESS_TOKEN`	Secret `secret`	yes	API Token
`url`	`KIMAI_URL`	URL `url`	yes	Kimai URL

Call Kimai Headlessly

Use the generic call form when another coding CLI or script needs a stable universal interface.

kosmo integrations:call kimai.kimai_list_timesheets '{
  "page": 1,
  "size": 1,
  "user": "example_user",
  "project": 1,
  "begin": "example_begin",
  "end": "example_end",
  "state": "example_state"
}' --json

Use the provider shortcut form for shorter human-facing commands.

kosmo integrations:kimai kimai_list_timesheets '{
  "page": 1,
  "size": 1,
  "user": "example_user",
  "project": 1,
  "begin": "example_begin",
  "end": "example_end",
  "state": "example_state"
}' --json

Agent Discovery Commands

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

kosmo integrations:docs kimai --json
kosmo integrations:docs kimai.kimai_list_timesheets --json
kosmo integrations:schema kimai.kimai_list_timesheets --json
kosmo integrations:search "Kimai" --json
kosmo integrations:list --json

All CLI Functions

Every function below can be called headlessly. The generic form is stable across all integrations; the provider shortcut is shorter but specific to Kimai.

`kimai.kimai_list_timesheets`

Read read

List time-tracking entries from Kimai. Supports filtering by user, project, date range, and state. Returns paginated results with timesheet details including duration, description, and associated project/activity.

Parameters: page, size, user, project, begin, end, state

Generic CLI call

kosmo integrations:call kimai.kimai_list_timesheets '{"page":1,"size":1,"user":"example_user","project":1,"begin":"example_begin","end":"example_end","state":"example_state"}' --json

Provider shortcut

kosmo integrations:kimai kimai_list_timesheets '{"page":1,"size":1,"user":"example_user","project":1,"begin":"example_begin","end":"example_end","state":"example_state"}' --json

`kimai.kimai_get_timesheet`

Read read

Get details of a specific timesheet entry from Kimai. Returns the full timesheet record including begin/end timestamps, duration, description, project, activity, and user information.

Parameters: id

Generic CLI call

kosmo integrations:call kimai.kimai_get_timesheet '{"id":1}' --json

Provider shortcut

kosmo integrations:kimai kimai_get_timesheet '{"id":1}' --json

`kimai.kimai_create_timesheet`

Write write

Create a new time-tracking entry in Kimai. Requires a begin timestamp and at least a project ID. Optionally specify an end time, activity, and description to categorize the time entry.

Parameters: begin, end, project, activity, description

Generic CLI call

kosmo integrations:call kimai.kimai_create_timesheet '{"begin":"example_begin","end":"example_end","project":1,"activity":1,"description":"example_description"}' --json

Provider shortcut

kosmo integrations:kimai kimai_create_timesheet '{"begin":"example_begin","end":"example_end","project":1,"activity":1,"description":"example_description"}' --json

`kimai.kimai_list_projects`

Read read

List projects from Kimai. Supports filtering by customer and visibility. Returns project details including name, customer, budget, and time budget information.

Parameters: page, size, customer, visible

Generic CLI call

kosmo integrations:call kimai.kimai_list_projects '{"page":1,"size":1,"customer":1,"visible":1}' --json

Provider shortcut

kosmo integrations:kimai kimai_list_projects '{"page":1,"size":1,"customer":1,"visible":1}' --json

`kimai.kimai_get_project`

Read read

Get details of a specific project from Kimai. Returns the full project record including name, customer, comment, budget, time budget, and visibility status.

Parameters: id

Generic CLI call

kosmo integrations:call kimai.kimai_get_project '{"id":1}' --json

Provider shortcut

kosmo integrations:kimai kimai_get_project '{"id":1}' --json

`kimai.kimai_list_customers`

Read read

List customers from Kimai. Supports filtering by visibility. Returns customer details including name, company, contact information, and associated project count.

Parameters: page, size, visible

Generic CLI call

kosmo integrations:call kimai.kimai_list_customers '{"page":1,"size":1,"visible":1}' --json

Provider shortcut

kosmo integrations:kimai kimai_list_customers '{"page":1,"size":1,"visible":1}' --json

`kimai.kimai_get_current_user`

Read read

Get the profile of the currently authenticated Kimai user. Returns user details including username, display name, email, timezone, and language preferences.

Parameters: none

Generic CLI call

kosmo integrations:call kimai.kimai_get_current_user '{}' --json

Provider shortcut

kosmo integrations:kimai kimai_get_current_user '{}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

`kimai.kimai_list_timesheets`

Operation: Read read
Schema command: kosmo integrations:schema kimai.kimai_list_timesheets --json

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`size`	integer	no	Number of results per page (default: 50).
`user`	string	no	Filter by user ID or username.
`project`	integer	no	Filter by project ID.
`begin`	string	no	Filter start date (ISO 8601, e.g., "2025-01-01T00:00:00"). Only entries starting on or after this date.
`end`	string	no	Filter end date (ISO 8601, e.g., "2025-01-31T23:59:59"). Only entries starting before or on this date.
`state`	string	no	Filter by state: "running" for active timers, "stopped" for completed entries. Omit for all.

`kimai.kimai_get_timesheet`

Get details of a specific timesheet entry from Kimai. Returns the full timesheet record including begin/end timestamps, duration, description, project, activity, and user information.

Operation: Read read
Schema command: kosmo integrations:schema kimai.kimai_get_timesheet --json

Parameter	Type	Required	Description
`id`	integer	yes	The timesheet entry ID.

`kimai.kimai_create_timesheet`

Create a new time-tracking entry in Kimai. Requires a begin timestamp and at least a project ID. Optionally specify an end time, activity, and description to categorize the time entry.

Operation: Write write
Schema command: kosmo integrations:schema kimai.kimai_create_timesheet --json

Parameter	Type	Required	Description
`begin`	string	yes	Start time in ISO 8601 format (e.g., "2025-01-15T09:00:00").
`end`	string	no	End time in ISO 8601 format (e.g., "2025-01-15T17:00:00"). Omit to start a running timer.
`project`	integer	yes	The project ID to associate the time entry with.
`activity`	integer	no	The activity ID to categorize the time entry (e.g., "Development", "Meeting").
`description`	string	no	A description of the work performed during this time entry.

`kimai.kimai_list_projects`

List projects from Kimai. Supports filtering by customer and visibility. Returns project details including name, customer, budget, and time budget information.

Operation: Read read
Schema command: kosmo integrations:schema kimai.kimai_list_projects --json

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`size`	integer	no	Number of results per page (default: 50).
`customer`	integer	no	Filter by customer ID to list only projects for a specific customer.
`visible`	integer	no	Visibility filter: 1 for visible projects only, 2 for hidden, 3 for all.

`kimai.kimai_get_project`

Get details of a specific project from Kimai. Returns the full project record including name, customer, comment, budget, time budget, and visibility status.

Operation: Read read
Schema command: kosmo integrations:schema kimai.kimai_get_project --json

Parameter	Type	Required	Description
`id`	integer	yes	The project ID.

`kimai.kimai_list_customers`

List customers from Kimai. Supports filtering by visibility. Returns customer details including name, company, contact information, and associated project count.

Operation: Read read
Schema command: kosmo integrations:schema kimai.kimai_list_customers --json

Parameter	Type	Required	Description
`page`	integer	no	Page number for pagination (default: 1).
`size`	integer	no	Number of results per page (default: 50).
`visible`	integer	no	Visibility filter: 1 for visible customers only, 2 for hidden, 3 for all.

`kimai.kimai_get_current_user`

Get the profile of the currently authenticated Kimai user. Returns user details including username, display name, email, timezone, and language preferences.

Operation: Read read
Schema command: kosmo integrations:schema kimai.kimai_get_current_user --json

Parameter	Type	Required	Description
No parameters.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.