Skip to main content
Glama
kimai-task-tracker-mcp

kimai-task-tracker-mcp

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

KIMAI_URL

sí

URL base de Kimai sin /api, p. ej. https://kimai.ejemplo.com

KIMAI_PROJECT_ID

sí

ID del proyecto cuyas tareas gestiona el servidor (entero)

KIMAI_API_TOKEN

sí

Token de API de Kimai (secret, nunca se loguea)

KIMAI_READ_ONLY

no

true expone solo las tools de lectura

Cómo obtener KIMAI_PROJECT_ID

  1. Abrí la app de Kimai y navegá al proyecto.

  2. La URL tiene la forma https://kimai.ejemplo.com/en/<cliente>/<proyecto>/.... El ID no aparece en la URL.

  3. Consultalo con la API: GET https://kimai.ejemplo.com/api/projects con el header X-AUTH-USER/X-AUTH-TOKEN (o Authorization: Bearer <token>), o desde Administración > API.

Instalación

Desde npm (producción)

npm install -g @byteflowsivar/kimai-task-tracker-mcp

Desde el repositorio (desarrollo)

pnpm install
pnpm build

Uso en desarrollo

KIMAI_URL=https://kimai.ejemplo.com \
KIMAI_PROJECT_ID=1 \
KIMAI_API_TOKEN=tu_token \
pnpm dev

Registro 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.json contiene el KIMAI_API_TOKEN real, así que está en .gitignore y no se commitea. Al clonar el repo, creá tu propio opencode.json con 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

list_tasks

lectura

Lista las tareas del proyecto con estado (todo, in_progress, done) y tiempo registrado. Filtros estado y term.

create_task

escritura

Crea una tarea (POST /api/activities). El nombre se normaliza a [TODO] ....

mark_task_done

escritura

Renombra a [DONE] .... Idempotente.

reopen_task

escritura

Renombra a [TODO] .... Idempotente.

start_task

escritura

Inicia un timer. Rechaza si la tarea ya tiene un registro en curso.

stop_timesheet

escritura

Detiene el registro activo (o uno específico con timesheet_id).

log_time

escritura

Registra tiempo manual con inicio/fin explícitos. Valida inicio < fin.

get_task_time

lectura

Registros de una tarea y su suma de duración.

get_project_summary

lectura

Total del proyecto y desglose por tarea, con rango desde/hasta opcional.

list_tags

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 login

  • Ser 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.0

El script release.sh hace lo siguiente:

  1. Bump de versión con npm version <tipo> --no-git-tag-version.

  2. Valida el tarball con npm pack --dry-run (solo dist/, README.md y package.json; nunca .env ni src/).

  3. Publica con npm publish, que ejecuta automáticamente el prepublishOnly (typecheck → test → build). Si alguno falla, no se publica nada.

  4. Verifica la versión publicada con npm view.

Nota: el script bumpea el version de package.json pero 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 200 en POST/PATCH (no 201). El cliente maneja errores 401/403/404/422 con el detalle de Kimai.

Available Tools

10 tools
create_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

    A4/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers