Clockify MCP

A local, single-user Model Context Protocol (MCP) server for Clockify. It runs on your machine over stdio, holds one Clockify API key, and exposes one Clockify workspace — time entries, projects, invoices, reports, scheduling, and more — as tools an AI client can call.

No account to create and no service to deploy: the binary runs as a subprocess of your MCP client.

Start from zero

You need a Go toolchain (go.dev/dl) and a Clockify account.

1. Build the binary

git clone https://github.com/apet97/go-clockify.git
cd go-clockify
go build -o clockify-mcp ./cmd/clockify-mcp

That produces a clockify-mcp binary in the current directory.

2. Get your Clockify credentials

• API key — open your Clockify profile settings and generate a key in the API section.
• Workspace ID — the identifier that appears after /workspaces/ in your Clockify workspace URL.

3. Check the setup

export CLOCKIFY_API_KEY="your-api-key"
export CLOCKIFY_WORKSPACE_ID="your-workspace-id"
./clockify-mcp doctor

doctor validates your configuration and prints every resolved setting. doctor --live additionally proves the key and workspace against Clockify.

4. Connect it to your MCP client

Point your MCP client at the binary. For a Claude .mcp.json:

{
  "mcpServers": {
    "clockify": {
      "command": "/absolute/path/to/clockify-mcp",
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key",
        "CLOCKIFY_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

The client launches clockify-mcp as a stdio subprocess. That is the whole setup — start with the clockify_status tool and go from there.

Tools

clockify-mcp loads the full 156-tool startup registry in a fixed order:

1. Workflow tools — high-level actions like start and stop work, log time, review a day, or invoice a client. Reach for these first.
2. Domain tools — direct create / read / update / delete for clients, projects, tasks, time entries, reports, invoices, expenses, time off, scheduling, and more.
3. Raw API fallback — for the rare endpoint with no dedicated tool.

The complete generated list is in docs/tool-catalog.md, and docs/agent-cookbook.md shows worked examples.

Raw API fallback

clockify_api_get and clockify_api_request reach Clockify endpoints that have no dedicated tool, scoped to your pinned workspace. Raw GET always works; raw POST, PUT, PATCH, and DELETE require CLOCKIFY_ENABLE_RAW_WRITES=true. Prefer the domain tools — raw writes are an explicit escape hatch.

Configuration

CLOCKIFY_API_KEY and CLOCKIFY_WORKSPACE_ID are required. Everything else is optional:

Variable	Default	Purpose
CLOCKIFY_BASE_URL	https://api.clockify.me/api/v1	Clockify API base URL
CLOCKIFY_TIMEZONE	system local	Timezone for date handling
CLOCKIFY_TOOLSET	all	Tool surface: core, business, admin, or all
CLOCKIFY_ENABLE_RAW_WRITES	false	Allow raw POST / PUT / PATCH / DELETE
CLOCKIFY_TOOL_TIMEOUT	45s	Per-tool timeout
CLOCKIFY_MAX_TOOL_RESULT_BYTES	50000	Result-size cap before truncation
MCP_LOG_LEVEL	info	Log level: debug, info, warn, error

Run clockify-mcp doctor to see every resolved value.

Compatibility

Capability	Support
MCP Protocol	2025-11-25
Transport	stdio
Clockify scope	one pinned workspace

Tests

go test ./...     # full suite against an in-memory fake Clockify server
make check        # adds the race detector and repo hygiene checks

Live tests run against real Clockify, are opt-in, and must target a sacrificial workspace — see docs/live-tests.md.

License

MIT.