go-clockify

clockify-mcp-go

A Model Context Protocol server for Clockify — plug any MCP client into your time-tracking workspace and let it log time, run reports, and manage projects on your behalf.

Works with Claude Code, Claude Desktop, Cursor, Codex, and anything else that speaks MCP.

Highlights

• 124 tools — 33 always-on (timer, entries, projects, reports, …) plus 91 on-demand (invoices, scheduling, approvals, admin, …) across 11 activatable groups.
• Resources & prompts — six clockify:// URI templates and five built-in prompt templates alongside the tool surface.
• Five policy modes — read_only, time_tracking_safe, safe_core, standard, full — plus dry-run preview support for every destructive tool.
• Three transports — stdio (default), streamable HTTP 2025-03-26 (shared services), opt-in gRPC behind a build tag. Cancellation, tools/list_changed, size limits, and malformed-JSON boundaries pinned with cross-transport parity tests.
• Stdlib-only default build — zero external runtime dependencies; the default binary links no OpenTelemetry, gRPC, or protobuf symbols (verified in CI).
• Signed releases — every binary and container image ships with cosign signatures, SPDX SBOM, and SLSA build provenance.

Contents

• Start Here · Install · Connect a client · Tool tiers · Policy modes · Configuration
• Common workflows · Architecture · Docker · Build and test
• Compatibility · Troubleshooting · Deployment · Contributing

Start Here

Pick a deployment profile and invoke the binary with --profile=<name> (or MCP_PROFILE=<name>). The profile applies a bundle of pinned defaults; explicit env overrides still win.

Not sure which profile matches your environment? Run clockify-mcp doctor — it prints every env var's effective value, its source (explicit / profile / default / empty), and whether Load() would succeed at startup. Add --strict for hosted-service posture checks. Exit code is 0 on a clean load, 2 on a load error, and 3 when strict posture findings are present.

Operators upgrading from before Wave I: see the operator overview and docs/operators/ for the deeper production checklist — profiles shortcut the common cases but do not replace ops review for critical deployments.

Install

# Go
go install github.com/apet97/go-clockify/cmd/clockify-mcp@latest

# npm (prebuilt binaries)
npx @apet97/clockify-mcp-go

# Or download a prebuilt binary from Releases:
# https://github.com/apet97/go-clockify/releases

Verify:

clockify-mcp --version

Get a Clockify API key from Profile → Advanced and export it:

export CLOCKIFY_API_KEY=your-key

Connect to an MCP client

The examples below are the local stdio path: your MCP client launches clockify-mcp as a subprocess and forwards CLOCKIFY_API_KEY in its environment.

Claude Code (CLI)

claude mcp add clockify -- clockify-mcp

Then set CLOCKIFY_API_KEY in your shell, or inline it: claude mcp add clockify -e CLOCKIFY_API_KEY=your-key -- clockify-mcp.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Cursor

Add to .cursor/mcp.json in your workspace:

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

Codex CLI

Add to your Codex MCP config:

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

npm wrapper (all clients)

If you installed via npm/npx, swap the command for:

{
  "command": "npx",
  "args": ["@apet97/clockify-mcp-go"]
}

Tool tiers

Tier 1 (33 tools, always loaded): timer, entries, projects, clients, tags, tasks, users, workspaces, reports, workflows, search, context.

Tier 2 (91 tools, 11 groups, on demand): invoices, expenses, scheduling, time off, approvals, shared reports, user admin, webhooks, custom fields, groups/holidays, project admin.

Call clockify_search_tools to discover and activate a Tier 2 group or a specific tool. Activation updates tools/list at runtime.

Policy modes

CLOCKIFY_POLICY controls which tools are exposed based on trust level:

Introspection tools (clockify_whoami, clockify_policy_info, clockify_search_tools, clockify_resolve_debug) are always available regardless of policy.

Configuration

The essentials (regenerate with go run ./cmd/gen-config-docs -mode=all):

Run clockify-mcp --help for the complete list (60+ variables covering concurrency, timeouts, control plane, metrics, auth, and CORS).

Common workflows

Start and stop a timer:

→ clockify_start_timer { "project": "My Project" }
← { "ok": true, "action": "timer_started", "data": { "id": "abc123" } }

→ clockify_stop_timer {}
← { "ok": true, "action": "timer_stopped" }

Log time retroactively:

→ clockify_log_time { "project": "Project Alpha", "start": "today 9:00", "end": "today 11:00", "description": "Code review" }

Discover a Tier 2 domain or tool:

→ clockify_search_tools { "query": "invoice" }
← { "count": 6, "all_results": [ { "type": "group", "name": "invoices" }, { "type": "tool", "name": "clockify_send_invoice" } ] }

Activate a Tier 2 domain:

→ clockify_search_tools { "activate_group": "invoices" }
← { "activated": "invoices", "tool_count": 12 }

Optionally activate a single Tier 2 tool:

→ clockify_search_tools { "activate_tool": "clockify_send_invoice" }
← { "activated": "clockify_send_invoice", "group": "invoices", "tool_count": 12 }

Preview a destructive operation first:

→ clockify_delete_entry { "entry_id": "abc123", "dry_run": true }
← { "dry_run": true, "preview": { "id": "abc123", "description": "Meeting" }, "note": "No changes were made." }

Execute after preview:

→ clockify_delete_entry { "entry_id": "abc123", "dry_run": false }
← { "ok": true, "action": "clockify_delete_entry", "data": { "deleted": true, "entryId": "abc123" } }

Architecture

Four clean layers: protocol core (internal/mcp/), Clockify client (internal/clockify/), tool surface (internal/tools/), and safety layer (internal/enforcement/). The protocol core has zero domain imports and plugs into the rest via Enforcement, Activator, Notifier, and ResourceProvider interfaces.

Docker

The published image defaults to the spec-strict streamable HTTP transport. The single-tenant-http profile wires the matching auth + control-plane defaults so the example below boots without a Postgres container or an OIDC issuer.

docker build -f deploy/Dockerfile -t clockify-mcp .

docker volume create clockify-mcp-data
export MCP_BEARER_TOKEN="$(openssl rand -base64 24)"

docker run -p 8080:8080 \
  -v clockify-mcp-data:/var/lib/clockify-mcp \
  -e MCP_PROFILE=single-tenant-http \
  -e CLOCKIFY_API_KEY=your-key \
  -e MCP_BEARER_TOKEN="$MCP_BEARER_TOKEN" \
  clockify-mcp

Validate the running server with the operator-facing endpoints:

curl http://127.0.0.1:8080/health

curl --oauth2-bearer "$MCP_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  http://127.0.0.1:8080/mcp

The repository also ships deploy/docker-compose.yml with a Caddy reverse proxy for TLS termination, and a Helm chart at deploy/helm/.

Build and test

make check   # fast inner loop: gofmt + go vet + go test
make verify  # full local pipeline: lint, coverage floors, fuzz-short,
             # build-tag checks, HTTP smoke, k8s render, govulncheck
             # (k8s/fips/vuln tiers auto-skip when their tools are missing)
make cover   # coverage report
make build   # binary with version from git tags

make verify mirrors the PR-blocking CI jobs that can run on a laptop — see CONTRIBUTING.md for the exact list of checks it runs locally versus the full CI set.

Go 1.25.9, stdlib only. Module path: github.com/apet97/go-clockify.

Compatibility

Troubleshooting

No tools visible — Check CLOCKIFY_BOOTSTRAP_MODE. In minimal mode most tools are hidden; use clockify_search_tools to discover them.

401 Unauthorized — API key is invalid or expired. Generate a new one.

Multiple workspaces — Set CLOCKIFY_WORKSPACE_ID explicitly.

Tool not found — It may be a Tier 2 tool. Use clockify_search_tools to find and activate its group.

Dry-run not working — Ensure CLOCKIFY_DRY_RUN=enabled (default) and pass "dry_run": true in tool call parameters.

Stale tool list — Stdio clients receive notifications/tools/list_changed after activation; HTTP clients must re-fetch tools/list.

Deployment

Reference Kubernetes manifests live in deploy/k8s/ and deploy/helm/: Deployment (non-root distroless, read-only root FS, dropped capabilities), NetworkPolicy (default-deny), PodDisruptionBudget, ServiceMonitor, and a PrometheusRule with burn-rate alerts for a 99.9% SLO.

For a single-page operator overview that links the threat model, transports, auth modes, deployment targets, runbooks, and compliance posture, see the operator overview.

Operator resources

• Shared Service profile
• Support Matrix
• Client Compatibility
• Deploy-Readiness Checklist
• Operator Guides (Shared Service vs Self-Hosted)

Contributing

See CONTRIBUTING.md.

Support

• Adoption expectations, response-time posture, v1.x wire-format stability guarantee: SUPPORT.md
• Governance (single-maintainer, merge gate, sensitive-area self-review): GOVERNANCE.md
• Security vulnerabilities: SECURITY.md (private disclosure channel)
• Bug reports and feature requests: GitHub Issues
• Release history: CHANGELOG.md · GitHub Releases
• Versioning, support window, breaking-change policy: docs/release-policy.md
• Documentation map: docs/README.md

License

MIT