kimai-task-tracker-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kimai-task-tracker-mcp start a timer for the task 'Write report'"
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-task-tracker-mcp
Servidor MCP (Model Context Protocol) para gestionar tareas de un proyecto Kimai y documentar el tiempo invertido. Una tarea es una Activity de Kimai; su estado se codifica en el nombre con la convención [TODO] / [DONE], y "en curso" se infiere de un timesheet activo.
Publicado en npm como @byteflowsivar/kimai-task-tracker-mcp.
Requisitos
Node.js >= 18
Una instancia de Kimai con API habilitada y un token de API
Related MCP server: timing-mcp-server
Configuración
El servidor se configura con variables de entorno, que el cliente MCP debe inyectar (el server no lee .env). Faltan las requeridas, aborta con un mensaje claro.
Variable | Obligatoria | Descripción |
| sí | URL base de Kimai sin |
| sí | ID del proyecto cuyas tareas gestiona el servidor (entero) |
| sí | Token de API de Kimai (secret, nunca se loguea) |
| no |
|
Cómo obtener KIMAI_PROJECT_ID
Abrí la app de Kimai y navegá al proyecto.
La URL tiene la forma
https://kimai.ejemplo.com/en/<cliente>/<proyecto>/.... El ID no aparece en la URL.Consultalo con la API:
GET https://kimai.ejemplo.com/api/projectscon el headerX-AUTH-USER/X-AUTH-TOKEN(oAuthorization: Bearer <token>), o desdeAdministración > API.
Instalación
Desde npm (producción)
npm install -g @byteflowsivar/kimai-task-tracker-mcpDesde el repositorio (desarrollo)
pnpm install
pnpm buildUso en desarrollo
KIMAI_URL=https://kimai.ejemplo.com \
KIMAI_PROJECT_ID=1 \
KIMAI_API_TOKEN=tu_token \
pnpm devRegistro en un cliente MCP
La forma más simple es ejecutar el paquete con npx, que lo descarga automáticamente sin instalación global:
{
"mcpServers": {
"kimai-task-tracker": {
"command": "npx",
"args": ["-y", "@byteflowsivar/kimai-task-tracker-mcp"],
"env": {
"KIMAI_URL": "https://kimai.ejemplo.com",
"KIMAI_PROJECT_ID": "1",
"KIMAI_API_TOKEN": "tu_token",
"KIMAI_READ_ONLY": "false"
}
}
}
}Si preferís instalarlo globalmente, el binario kimai-task-tracker queda disponible en el PATH:
{
"mcpServers": {
"kimai-task-tracker": {
"command": "kimai-task-tracker",
"env": {
"KIMAI_URL": "https://kimai.ejemplo.com",
"KIMAI_PROJECT_ID": "1",
"KIMAI_API_TOKEN": "tu_token",
"KIMAI_READ_ONLY": "false"
}
}
}
}También podés apuntar command a node y args a la ruta del dist/index.js del paquete:
{
"mcpServers": {
"kimai-task-tracker": {
"command": "node",
"args": ["/ruta/al/paquete/dist/index.js"],
"env": {
"KIMAI_URL": "https://kimai.ejemplo.com",
"KIMAI_PROJECT_ID": "1",
"KIMAI_API_TOKEN": "tu_token",
"KIMAI_READ_ONLY": "false"
}
}
}
}Uso con opencode
El repo incluye un opencode.json que registra el servidor MCP solo para este proyecto. Las variables van directamente en el bloque environment (así el usuario no necesita exportarlas ni tener el paquete instalado globalmente):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"kimai-task-tracker": {
"type": "local",
"command": ["npx", "-y", "@byteflowsivar/kimai-task-tracker-mcp"],
"environment": {
"KIMAI_URL": "https://kimai.ejemplo.com",
"KIMAI_PROJECT_ID": "1",
"KIMAI_API_TOKEN": "tu_token"
},
"enabled": true
}
}
}⚠️ Seguridad:
opencode.jsoncontiene elKIMAI_API_TOKENreal, así que está en.gitignorey no se commitea. Al clonar el repo, creá tu propioopencode.jsoncon tus valores (podés copiar el bloque de arriba).
Tras reiniciar opencode, el server kimai-task-tracker aparece con sus 10 tools; probá list_tasks para verificar la conexión.
Tools
Tool | Lectura/Escritura | Descripción |
| lectura | Lista las tareas del proyecto con estado ( |
| escritura | Crea una tarea ( |
| escritura | Renombra a |
| escritura | Renombra a |
| escritura | Inicia un timer. Rechaza si la tarea ya tiene un registro en curso. |
| escritura | Detiene el registro activo (o uno específico con |
| escritura | Registra tiempo manual con |
| lectura | Registros de una tarea y su suma de duración. |
| lectura | Total del proyecto y desglose por tarea, con rango |
| lectura | Lista los tags existentes. |
Con KIMAI_READ_ONLY=true solo se exponen las tools de lectura.
Desarrollo
pnpm types # regenera src/types.ts desde openapi/openapi.json
pnpm test # corre vitest
pnpm typecheck # typecheck de TypeScript strict
pnpm build # compila a dist/ (sin tests)Publicación
El paquete se publica en npm bajo la org @byteflowsivar. Requiere:
Estar logueado en npm:
npm loginSer owner de la org
byteflowsivar:npm org ls byteflowsivar
Paso a paso
pnpm release patch # 0.1.0 → 0.1.1
pnpm release minor # 0.1.0 → 0.2.0
pnpm release major # 0.1.0 → 1.0.0El script release.sh hace lo siguiente:
Bump de versión con
npm version <tipo> --no-git-tag-version.Valida el tarball con
npm pack --dry-run(solodist/,README.mdypackage.json; nunca.envnisrc/).Publica con
npm publish, que ejecuta automáticamente elprepublishOnly(typecheck→test→build). Si alguno falla, no se publica nada.Verifica la versión publicada con
npm view.
Nota: el script bumpea el
versiondepackage.jsonpero no crea un commit ni un tag de git. Creá el commit/tag después del release si lo querés versionar también en el repo.
Licencia
MIT — ver LICENSE.
Notas
Los tags solo se aceptan en el registro de tiempo (
start_task/log_time), porque Kimai no soporta tags en activities.Kimai responde
200enPOST/PATCH(no201). El cliente maneja errores401/403/404/422con el detalle de Kimai.
Available Tools
10 toolscreate_taskA
Crea una tarea en el proyecto configurado. El nombre no debe llevar prefijo de estado.
Inputs: nombre (required), color, comentario.
get_project_summaryA
Resumen de tiempo del proyecto: total y desglose por tarea, con rango opcional.
Inputs: desde, hasta.
get_task_timeA
Devuelve los registros de tiempo de una tarea y su suma total.
Inputs: task_id (required).
list_tagsA
Lista los tags existentes en Kimai.
Inputs: no named parameters.
list_tasksB
Lista las tareas del proyecto configurado con su estado (todo, in_progress, done) y el tiempo registrado.
Inputs: term, estado.
log_timeA
Registra tiempo manual con inicio y fin explícitos. inicio debe ser anterior a fin.
Inputs: fin (required), inicio (required), task_id (required), tags, +1 more.
mark_task_doneA
Marca una tarea como finalizada (prefijo [DONE]). Idempotente.
Inputs: task_id (required).
reopen_taskA
Reabre una tarea finalizada (prefijo [TODO]). Idempotente.
Inputs: task_id (required).
start_taskA
Inicia un timer sobre una tarea. Rechaza si ya hay un registro en curso.
Inputs: task_id (required), tags, descripcion.
stop_timesheetA
Detiene el registro en curso. Si no se pasa timesheet_id, detiene el activo de la tarea.
Inputs: task_id, timesheet_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct operation: timer control (start_task, stop_timesheet), manual logging (log_time), time queries (get_task_time, get_project_summary), task management (list_tasks, create_task, mark_task_done, reopen_task), and tag listing (list_tags). Even similar actions like start_task and log_time are clearly separated by explicit vs. timer-based logging.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., start_task, get_project_summary, mark_task_done). No mixed conventions or vague verbs; the naming is predictable and readable.
With 10 tools, the set is well-scoped for a task tracker with time tracking. Each tool serves a clear purpose and covers the essential operations without redundancy or bloat.
The toolset covers the core lifecycle: task creation, listing, status updates (done/reopen), and comprehensive time tracking (start, stop, manual log, queries, project summary). Minor gaps exist, such as no update/delete task or tag assignment, but these are not critical for the primary workflow.
Maintenance
Related MCP Connectors
timesheet.io MCP server - manage timers, projects, tasks and reports
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
Toggl 2.0 MCP server for tasks, projects, time entries, and workspace operations.
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server for Productive.io that enables users to log time, inspect projects, and manage time entries using natural language commands. It features fuzzy project matching, local caching, and remembers default services per project for streamlined time tracking.14MIT
- AlicenseNot gradedqualityDmaintenanceThis MCP server enables AI assistants to interact with the Timing application for managing time tracking and tasks, including project and time entry operations.7MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for managing Kaiten tasks through AI agents like Claude, enabling task retrieval, creation, updating, and time logging.24 npm2MIT
- AlicenseAqualityCmaintenanceMCP server for Kimai time-tracking that provides read access to the full API and guarded write tools for timesheets, with explicit authorization and backups.2822 npmAGPL 3.0