triagons-clockify-mcp

An MCP (Model Context Protocol) server that wraps the Clockify API, deployed as a Google Cloud Function with HTTP/SSE transport.

Tools

| Tool | Description | |------|-------------| | get_hours_by_project | Total hours, billable hours, and per-member breakdown for a project + date range | | get_unbilled_hours | All uninvoiced billable hours for a client, estimated value, last entry date | | get_team_utilization | Hours logged and capacity % per team member for the current month |

Note: get_team_utilization and get_unbilled_hours require workspace admin access in Clockify to return full team data.

Authentication

Each user passes their own Clockify API key in the Authorization header. The server stores no secrets — it simply forwards the key to Clockify on each request.

Claude Desktop ──Authorization: Bearer <clockify-api-key>──► Cloud Function ──X-Api-Key: <key>──► Clockify

Get your API key at https://app.clockify.me/user/settings → API section.

Local development

cp .env.example .env
# Set CLOCKIFY_API_KEY in .env for local testing

npm install
npm run dev        # starts on http://localhost:8080

Test with curl:

curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer YOUR_CLOCKIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'

Deploy to Google Cloud Functions

Prerequisites

• gcloud CLI installed and authenticated
• A GCP project with Cloud Functions and Cloud Build APIs enabled

gcloud services enable cloudfunctions.googleapis.com cloudbuild.googleapis.com

Deploy (Gen 2 — recommended)

Gen 2 runs on Cloud Run and supports long-lived SSE connections.

gcloud functions deploy triagons-clockify-mcp \
  --gen2 \
  --runtime nodejs20 \
  --region us-central1 \
  --source . \
  --entry-point triagonsClockifyMcp \
  --trigger-http \
  --allow-unauthenticated \
  --timeout 3600s \
  --min-instances 0 \
  --max-instances 10

The command prints the function URL when it finishes. The MCP endpoint is at <FUNCTION_URL>/mcp.

Note on timeout: SSE connections are long-lived. Gen 2 supports up to 3600s. For longer sessions, deploy to Cloud Run directly.

Deploy (Gen 1)

Gen 1 has a hard 9-minute timeout — SSE sessions disconnect after that.

gcloud functions deploy triagons-clockify-mcp \
  --runtime nodejs20 \
  --region us-central1 \
  --source . \
  --entry-point triagonsClockifyMcp \
  --trigger-http \
  --allow-unauthenticated \
  --timeout 540s

Claude Desktop configuration

Add this to your claude_desktop_config.json. Each person uses their own Clockify API key:

{
  "mcpServers": {
    "clockify": {
      "url": "https://REGION-PROJECT_ID.cloudfunctions.net/triagons-clockify-mcp/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CLOCKIFY_API_KEY"
      }
    }
  }
}

Or with a custom domain:

{
  "mcpServers": {
    "clockify": {
      "url": "https://mcp.triagons.ai/clockify/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CLOCKIFY_API_KEY"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | CLOCKIFY_API_KEY | Local dev only | API key for local npm run dev (not used in production) | | CLOCKIFY_WORKSPACE_ID | No | Skip auto-detection by pinning a workspace ID | | PORT | No | Local dev port (default: 8080) |

Notes on billing data

get_unbilled_hours returns estimated_value_usd: null when Clockify has no billing rates configured for the entries. Set hourly rates on projects or users in Clockify for this field to populate.