kimai-timelog-mcp

Un servidor MCP que permite a Claude (o a cualquier cliente LLM compatible con MCP) leer y escribir tus registros de horas de Kimai. Dices "registra de 9 a 12:30 en la renovación del portal, arreglando la redirección de inicio de sesión" y la entrada aparece en Kimai.

Cada solicitud se hace como tú: utiliza tu token personal de la API de Kimai, por lo que solo puede ver y cambiar lo que tu cuenta de Kimai tenga permitido.

1. Obtén un token de API de Kimai

1. Abre Kimai → haz clic en tu nombre (arriba a la derecha) → Mi perfil → pestaña Acceso a API.

2. Crea un token, dale un nombre como claude y cópialo inmediatamente; Kimai solo lo muestra una vez.

Related MCP server: Kimai MCP Server

2. Instalación

Necesitas uv (recomendado) o Python 3.10+.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Luego, una de estas opciones:

A. Desde una carpeta compartida o repositorio git (lo que harán tus compañeros)

uvx --from git+https://github.com/Alpha101Code/kimai-timelog-mcp kimai-mcp --check

B. Desde una copia local

cd /path/to/kimai-timelog-mcp
uv run kimai-mcp --check

--check comprueba la URL y el token e imprime tus proyectos visibles. Define primero las dos variables de entorno:

export KIMAI_URL=https://timesheet-sd.maccs.mu
export KIMAI_API_TOKEN=your-token-here

3. Conéctalo a tu cliente

Claude Desktop

Configuración → Desarrollador → Editar configuración y añade:

{
  "mcpServers": {
    "kimai": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Alpha101Code/kimai-timelog-mcp", "kimai-mcp"],
      "env": {
        "KIMAI_URL": "https://timesheet-sd.maccs.mu",
        "KIMAI_API_TOKEN": "your-token-here"
      }
    }
  }
}

Reinicia Claude Desktop. En Windows, usa uvx.exe si uvx no se encuentra en PATH.

Claude Code

claude mcp add kimai \
  --env KIMAI_URL=https://timesheet-sd.maccs.mu \
  --env KIMAI_API_TOKEN=your-token-here \
  -- uvx --from git+https://github.com/Alpha101Code/kimai-timelog-mcp kimai-mcp

Cursor / Windsurf / Cline / Zed

La misma estructura JSON que en Claude Desktop, en el archivo de configuración MCP de ese cliente (~/.cursor/mcp.json para Cursor).

Cualquier otro cliente

Es un servidor MCP stdio estándar. Comando: kimai-mcp. Configuración: las dos variables de entorno anteriores.

Herramientas

Decisiones de diseño que conviene conocer

• Nombres, no IDs. project: "Portal Revamp" funciona; también un fragmento único como "portal". Los nombres ambiguos devuelven un error que enumera los candidatos, que el modelo puede plantearte como pregunta.

• Entrada de tiempo flexible. date: today, yesterday, monday, 3 days ago, 2026-08-24, 25/08/2026. start/end: 09:00, 9am, 5.30pm, 0930. duration: 1h30m, 90m, 1.5h, 1:30.

• Tu zona horaria. Kimai informa la zona horaria del propietario del token; todo se resuelve a partir de esa, no del reloj del servidor.

• Sin horas inventadas. log_time necesita inicio+fin, inicio+duración o duración; si no se incluye ninguno, devuelve un error que le indica al modelo que te pregunte en lugar de adivinar.

• El borrado es en dos pasos. La primera llamada devuelve lo que se eliminaría; solo una segunda llamada con confirm: true lo elimina.

Ejemplos de prompts

Log 9:00–12:30 today on Portal Revamp, development, "fixed the login redirect".
What did I log this week? Break it down by project.
Same as yesterday afternoon, but for today.
Start a timer on Internal Tools / Admin.
I forgot Monday — 4 hours on Mobile App, release testing.
Move entry 512 to start at 10:15 instead.

Cómo desplegarlo para tus compañeros

Cada persona necesita tres cosas: uv instalado, su propio token de Kimai y el bloque de configuración anterior. Nada se comparte entre usuarios: no hay ningún servidor que ejecutar ni token central.

Si más adelante quieres un único servidor alojado en lugar de una instalación por máquina, la capa de herramientas se mantiene igual; solo cambia el transporte en __main__.py.

Seguridad

• El token equivale a una contraseña. Se guarda en el archivo de configuración de tu cliente en tu propia máquina: no lo subas a un repositorio ni lo pegues en un documento compartido.

• Establece una fecha de caducidad para los tokens en Kimai y rótalos.

• El servidor solo se comunica con KIMAI_URL. No tiene ningún otro acceso a la red, ni acceso al sistema de archivos, ni shell.

• Si tu Kimai es de acceso solo interno, esto debe ejecutarse en una máquina que pueda alcanzarlo (VPN o red de oficina).

Desarrollo

src/kimai_mcp/
  client.py     Kimai REST client — auth, errors, name→id resolution, caching
  timeutil.py   parsing for human dates, times and durations
  server.py     the MCP tools
  __main__.py   stdio entrypoint + --check
tests/
  mock_kimai.py a stand-in Kimai instance
  test_e2e.py   drives the real server over stdio against it

Ejecuta la suite (no se necesita una instancia de Kimai):

uv run --with mcp --with httpx python tests/test_e2e.py

Compatibilidad

Funciona con las dos versiones principales del SDK de Python para MCP: mcp 1.x (FastMCP) y 2.x (MCPServer). El servidor elige la correcta en el momento de la importación, y los fallos previstos subclasifican el ToolError del SDK para que el mensaje llegue al modelo en lugar de un "error al ejecutar la herramienta" genérico. La suite se ejecuta contra ambos en CI.

La distribución se llama kimai-timelog-mcp (igual que el repositorio); el comando que instala es kimai-mcp.

Desarrollado contra la API REST de Kimai 2 (/api, Authorization: Bearer <token>). Referencia de endpoints: https://www.kimai.org/documentation/rest-api.html y el /api/doc de tu propia instancia.