clockify-mcp-server

Registra tus horas de proyecto en Clockify pidiéndoselo a tu agente, en lugar de hacer clic en la interfaz web.

"añade 4h a ACME cada mañana de esta semana y 4h a Evil Corp cada tarde"

→ una sola solicitud de aprobación, 10 entradas creadas, 40h en total.

Un servidor MCP local de stdio. Cada persona lo ejecuta por su cuenta con su propia clave de API — no se comparte ni se aloja nada.

Las horas son siempre locales a la zona horaria de tu perfil de Clockify. Dices 09:00, el servidor lee settings.timeZone de tu perfil de Clockify y convierte a UTC. Nunca lidias con UTC, y tampoco el agente.

Aún no soportado: etiquetas, clientes, temporizadores en ejecución (iniciar/detener), editar entradas existentes, informes.

Úsalo

Todo lo que necesitas si solo quieres registrar tiempo. Lleva unos dos minutos.

1. Instala bun (probado en 1.3.14) y las dependencias:

curl -fsSL https://bun.sh/install | bash # install bun if needed
git clone <this-repo> && cd clockify-mcp-server
bun install

No hay paso de compilación — bun ejecuta el TypeScript directamente.

2. Obtén tu clave de API de Clockify:

• Clockify → tu avatar → Preferencias → pestaña ADVANCED → Administrar claves de API → GENERATE NEW

3. Registra el servidor con tu agente.

Claude Code — copia esto tal cual, desde la raíz del repo que acabas de clonar:

claude mcp add clockify -s user -e CLOCKIFY_API_KEY=<key> -- bun "$PWD/src/index.ts"

-s user lo escribe en tu configuración personal para que se cargue en todos los proyectos, no solo este (el ámbito por defecto, local, lo vincularía a este directorio). $PWD lo expande tu shell antes de que claude lo vea, así que la ruta guardada es absoluta.

Cualquier otro harness (Cursor, VS Code, Zed, Claude Desktop…) — las mismas tres cosas en su configuración MCP. Imprime la ruta para pegarla:

echo "$PWD/src/index.ts"

{
  "mcpServers": {
    "clockify": {
      "command": "bun",
      "args": ["<paste the absolute path here>"],
      "env": { "CLOCKIFY_API_KEY": "<key>" }
    }
  }
}

La ruta debe ser absoluta: tu agente inicia el servidor desde el directorio en el que esté trabajando, no desde este repo.

4. Compruébalo — en una sesión nueva:

list my clockify projects
log 2 hours on <project> today from 09:00 to 11:00, description test
show my clockify entries for this week
delete that entry

Abre la interfaz web de Clockify después del segundo prompt y confirma que la entrada dice 09:00–11:00. Si muestra una hora distinta, la zona horaria de tu perfil de Clockify no es la que crees — arréglala en las preferencias de Clockify, todo aquí se deriva de ella.

Entorno

Si algo sale mal

• CLOCKIFY_API_KEY is not set — la clave no llegó al proceso del servidor. Ponla en el env de la configuración del harness, no en tu shell.

• Ambiguous project "x". Candidates: … — es deliberado. El servidor se niega a adivinar un id; usa uno de los nombres listados.

• 404 en cada llamada — tu espacio de trabajo está en un host regional. Configura CLOCKIFY_API_BASE.

• Las entradas se registran a la hora equivocada — revisa la zona horaria de tu perfil de Clockify (ver paso 4).

Desarróllalo

Nada de esto es necesario para usar el servidor.

bun test      # unit tests, no network
bun run check # biome format + lint, applies fixes
bun run start # start the server on stdio (needs CLOCKIFY_API_KEY)

bun install también instala los git hooks (prepare → lefthook install), así que biome check --write se ejecuta sobre tus archivos en stage al momento de commit y vuelve a añadir lo que haya corregido. No hay nada más que configurar.

Para ejecuciones locales, bun carga automáticamente .env desde la raíz del repo, así que un CLOCKIFY_API_KEY=<key> ahí (ignorado por git) te ahorra volver a escribirlo. Eso solo funciona cuando el directorio de trabajo es el repo, que es por lo que la configuración del harness de arriba pasa la clave explícitamente.

Estructura

src/clockify.ts      # API client, memoised user/project/task lookups, timezone conversion
src/index.ts         # McpServer + the four tools + stdio wiring
src/clockify.test.ts # the parts worth testing: DST conversion, name resolution, payload building
docs/                # Clockify API request/response samples
plans/               # what was built and what was deliberately left out

El código interesante es localToUtc / interval en src/clockify.ts — un round-trip con Intl.DateTimeFormat de la stdlib, sin librería de fechas. Cámbialo y ejecuta bun test; los casos de horario de verano son los que detectan errores.

Para entregarlo a alguien sin bun: bun build --compile --outfile clockify-mcp src/index.ts produce un binario autocontenido para apuntar el harness en su lugar.