convez.ai
MCP ServerIntegração & APIsIntermediário
themkn

Clockify MCP Server

themkn/clockify-mcp

Controle o Clockify pelo Claude com comandos em linguagem natural

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra o Clockify ao Claude, permitindo gerenciar entradas de tempo, projetos, tarefas, tags e clientes via linguagem natural. Ideal para quem quer controlar rastreamento de horas diretamente do terminal sem sair do fluxo de trabalho.

Instalação

$npx convez-ai themkn/clockify-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 6 dias
Versão
v1.0.3
Issues abertas
7
Contribuidores
6

Casos de uso

  • Iniciar e parar timers de rastreamento de tempo sem deixar o terminal
  • Gerenciar projetos, tarefas e tags do Clockify via Claude Code
  • Automatizar logs de tempo entry para fluxos de desenvolvimento e freelancing

Veredito

Integração bem estruturada e segura com o Clockify. A configuração granular de permissões garante fluxo descomplicado para operações rotineiras sem comprometer a segurança em ações destrutivas. Solução prática para quem precisa gerenciar tempo sem contexto-switching.

README

A tradução para o português deste README ainda está na fila.

clockify-mcp — Clockify MCP Server for Claude Code

npm

An MCP server for Clockify time tracking. Start and stop timers, manage time entries, projects, tasks, tags, and clients — directly from Claude Code or any MCP-compatible client.

What is Clockify?

Clockify is a free time tracking tool used by freelancers and teams to log work hours, generate reports, and manage projects. It works across web, desktop, and mobile — and its generous free tier covers unlimited users and tracking. This MCP server lets you control Clockify with natural language through Claude, so you never have to leave your terminal.

Prerequisites

  • A Clockify account — sign up for free (the free plan is all you need)
  • A personal API key — once logged in, go to Profile settings → API → Generate
  • Your workspace ID — visible in the Clockify URL after selecting a workspace (e.g. app.clockify.me/workspaces/<id>/...)
  • Node.js 24+

Install

npm install -g @themkn/clockify-mcp

The binary is called clockify-mcp regardless of the scoped package name.

(Or point Claude's MCP config at the built JS locally — see below.)

Configure

The server reads a JSON config from ~/.clockify-mcp/config.json. Create it with permission 600:

mkdir -p ~/.clockify-mcp
chmod 700 ~/.clockify-mcp
cat > ~/.clockify-mcp/config.json <<'EOF'
{
  "apiKey": "YOUR_CLOCKIFY_PERSONAL_API_KEY",
  "workspaceId": "YOUR_WORKSPACE_ID"
}
EOF
chmod 600 ~/.clockify-mcp/config.json

Paste the API key and workspace ID from the prerequisites above. The server will refuse to start if the config file is group- or world-readable.

Hook into Claude Code

Add an entry to your Claude MCP config (typically ~/.config/claude/mcp.json or the per-project .claude/mcp.json):

{
  "mcpServers": {
    "clockify": {
      "command": "clockify-mcp"
    }
  }
}

Recommended permissions

By default Claude Code asks for permission on every Clockify tool call. A blanket mcp__clockify__* allow works, but it also auto-approves destructive calls like delete_time_entry. A tiered policy keeps the daily flow frictionless while making destructive or rare operations explicit.

Add this to your ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__clockify__get_current_user",
      "mcp__clockify__get_workspace",
      "mcp__clockify__get_project",
      "mcp__clockify__get_time_entry",
      "mcp__clockify__get_running_timer",
      "mcp__clockify__list_clients",
      "mcp__clockify__list_projects",
      "mcp__clockify__list_tasks",
      "mcp__clockify__list_tags",
      "mcp__clockify__list_time_entries",
      "mcp__clockify__start_timer",
      "mcp__clockify__stop_timer",
      "mcp__clockify__create_time_entry",
      "mcp__clockify__update_time_entry"
    ]
  }
}

What this does:

  • Reads + time-entry writes (the list above) run without prompting — these are the daily flow.
  • Catalog writes (create_project, update_client, etc.) and all delete_* tools are not listed, so Claude Code will prompt before each call. Catalog edits are rare from the MCP and deletes should be deliberate.

If you want a stricter setup, keep a wildcard allow and add a deny block for the destructive tools — deny blocks the call entirely (no prompt, no override):

{
  "permissions": {
    "allow": ["mcp__clockify__*"],
    "deny": [
      "mcp__clockify__delete_client",
      "mcp__clockify__delete_project",
      "mcp__clockify__delete_task",
      "mcp__clockify__delete_tag",
      "mcp__clockify__delete_time_entry"
    ]
  }
}

Tools

Grouped by resource:

ResourceTools
Time entrieslist_time_entries, get_time_entry, create_time_entry, update_time_entry, delete_time_entry, start_timer, stop_timer, get_running_timer
Projectslist_projects, get_project, create_project, update_project, delete_project
Taskslist_tasks, create_task, update_task, delete_task
Tagslist_tags, create_tag, update_tag, delete_tag
Clientslist_clients, create_client, update_client, delete_client
Metaget_current_user, get_workspace

Notes:

  • All timestamps are ISO 8601 (YYYY-MM-DDTHH:mm:ssZ). Claude interprets relative phrases like "yesterday 9am" before calling the tool.
  • Tools accept IDs, not names. Claude lists projects/tasks/tags/clients first, picks the matching id, then acts.
  • delete_project tries a hard delete; if Clockify refuses because the project has time entries, the server archives it instead. The response reports { "action": "deleted" } or { "action": "archived" }.

Example prompts

Once the server is running, try asking Claude things like:

PromptWhat happens
"Start a timer for the standup meeting"Starts a running timer with that description
"Stop my timer"Stops the currently running timer
"How many hours did I log this week?"Lists recent time entries and totals them
"Log 2 hours yesterday for the Website Redesign project"Creates a time entry on the right project
"Create a project called 'Brand Refresh' for client Acme"Creates a new project linked to an existing client
"Show me all time entries from last Monday"Fetches entries filtered by date
"Tag my last time entry with 'billable'"Updates the most recent entry with a tag
"Delete the 'test-cleanup' tag"Removes a tag by name
"What projects do we have?"Lists all projects in the workspace
"Am I tracking time right now?"Checks for a running timer

Claude handles the translation from natural language to API calls — you just describe what you want in plain English.

Security

  • The API key in ~/.clockify-mcp/config.json grants full access to your Clockify account. This server cannot narrow that scope — Clockify's API does not offer read-only personal tokens. Rotate the key if you suspect exposure.
  • The key is never logged or returned in any tool response. Errors are scrubbed defensively before being surfaced.
  • The only network destination is https://api.clockify.me; there is no telemetry.
  • Run the server as your user — never via sudo.

Report vulnerabilities per SECURITY.md.

Development

npm install
npm run typecheck
npm test
npm run build

Optional: add npm run test:live later for integration tests against a real workspace (not run in CI).

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados