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

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.