clockify-mcp

A Model Context Protocol server for the Clockify time-tracking API.

Give your AI assistant access to your Clockify data — query workspaces, projects, and time entries, generate reports, log hours, and manage clients, invoices, and more — all through natural language.

112 tools across 18 domains. Read-only by default, with optional write operations behind explicit opt-in.

Install in one click

The easiest way to use this server with Claude Desktop (and other MCPB-compatible clients) is the prebuilt bundle:

➡️ Download clockify-mcp.mcpb — then double-click it. Claude Desktop opens the installer, prompts for your Clockify API key, and you're done. No Python, no npx/uvx, no config files.

The .mcpb is attached to every GitHub Release and mirrored on Smithery. Prefer a package manager or container? See Quick start below.

What can it do?

48 read-only tools are available today (Phase 0–8b — 18 domains). 64 write tools (create/update/delete across clients, projects, tasks, tags, time entries, holidays, expenses, and expense categories, plus time-off policy/request management, approval submit/resubmit/update, custom-field create/update/delete and project assignment, scheduling assignment management, invoice and payment management, shared-report management, and webhook create/update/delete/token) register when you set CLOCKIFY_ACCESS_MODE=full (or the back-compat CLOCKIFY_ENABLE_WRITES=true). A middle time-tracking mode exposes only the time-entry writes for logging hours — see Access modes.

† Time off, Holidays, Expenses, Approvals, Custom fields, Scheduling, Invoices, and Webhooks are paid Clockify features — these tools error (HTTP 402/403/404) on plans without them. ‡ generate_attendance_report and generate_expense_report (and export_report for those two types) need the workspace's attendance/Expenses add-ons; the time-based reports (detailed/summary/weekly) and shared reports work on the free plan.

Write tools (opt-in — set CLOCKIFY_ACCESS_MODE=full):

† Time off, Holidays, Expenses, Approvals, Custom fields, Scheduling, Invoices, and Webhooks are paid Clockify features — these tools error (HTTP 402/403/404) on plans without them.

create_expense and update_expense accept an optional local receipt file, uploaded via multipart.

Quick start

1. Install

pip install clockify-mcp

Or run without installing (requires uv):

uvx clockify-mcp

Or use the container image (published to GHCR on every release):

docker run --rm -i -e CLOCKIFY_API_KEY=your-key ghcr.io/tracegazer/clockify-mcp:latest

2. Connect to Claude Desktop

Add this to your claude_desktop_config.json:

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

Restart Claude Desktop. Ask: "What workspaces do I have in Clockify?"

{
  "mcpServers": {
    "clockify": {
      "command": "clockify-mcp",
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key"
      }
    }
  }
}

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

3. Get your API key

Log into Clockify → Profile Settings → API → copy your API key.

Configuration

Configuration resolves in this order (highest priority first):

1. Environment variables (always win)
2. TOML config at ~/.config/clockify-mcp/config.toml