Clockify MCP Server

An MCP server for the Clockify time-tracking API. It exposes Clockify operations as Model Context Protocol tools so any MCP-compatible client (Claude Desktop, Cursor, etc.) can query and manage your time-tracking data in natural language.

112 tools across 18 domains — 48 read tools (always on) + 64 write tools (opt-in).

Features

• Core: workspaces, users, groups, clients, projects, tasks, tags
• Time entries: list/get/create/update/delete, duplicate, bulk update, start/stop timers, log time for another user
• Reports: detailed, summary, weekly, attendance, and expense reports — as JSON or exported to PDF/CSV/XLSX
• Shared reports: list, generate-by-id, and full CRUD
• More domains: time off, holidays, expenses (with receipt upload), approvals, custom fields, scheduling, invoices, webhooks
• Pagination: per-page or fetch_all to follow pagination automatically
• Observability: optional OpenTelemetry OTLP export (traces, metrics, logs)

Install

Requires Python 3.12+ and uv. No install step — uvx runs it on demand.

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "clockify": {
      "command": "uvx",
      "args": ["clockify-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your-clockify-api-key"
      }
    }
  }
}

Get your API key from Clockify → Profile Settings → API.

Configuration

┌───────────────────────────────┬──────────┬──────────────────────────────────────────────────┐
│           Variable            │ Required │                   Description                    │
├───────────────────────────────┼──────────┼──────────────────────────────────────────────────┤
│ CLOCKIFY_API_KEY              │ yes      │ Your Clockify API key (sent as X-Api-Key)        │
├───────────────────────────────┼──────────┼──────────────────────────────────────────────────┤
│ CLOCKIFY_ACCESS_MODE          │ no       │ read (default), time-tracking, or full           │
├───────────────────────────────┼──────────┼──────────────────────────────────────────────────┤
│ CLOCKIFY_DEFAULT_WORKSPACE_ID │ no       │ Default workspace when a tool omits workspace_id │
├───────────────────────────────┼──────────┼──────────────────────────────────────────────────┤
│ CLOCKIFY_REGION               │ no       │ Regional endpoint (e.g. euc1)                    │
├───────────────────────────────┼──────────┼──────────────────────────────────────────────────┤
│ CLOCKIFY_TELEMETRY            │ no       │ Set true to enable OpenTelemetry OTLP export     │
└───────────────────────────────┴──────────┴──────────────────────────────────────────────────┘

Access modes

Read-only by default. Set CLOCKIFY_ACCESS_MODE:

- read — read tools only (default)
- time-tracking — adds time-entry writes for logging hours
- full — all 64 write tools (CLOCKIFY_ENABLE_WRITES=true is an alias)

delete_* tools are irreversible.

Paid features

Time off, holidays, invoices, approvals, expenses, custom fields, and scheduling require a paid Clockify plan and the module enabled in Workspace Settings. The server returns clear error categories (PLAN_REQUIRED / ACCESS_DENIED) so you know which is missing.
Time-based and shared reports work on the free plan.

Links

- PyPI: https://pypi.org/project/clockify-mcp/
- GitHub: https://github.com/tracegazer/clockify-mcp
- License: MIT