@lewinnovation/clockify-mcp-server

MCP (Model Context Protocol) server for the Clockify REST API. It exposes a small set of curated tools for common workflows plus a generic clockify_request tool for other documented /v1/... endpoints.

Requirements

• Node.js 20+
• pnpm 10+
• A Clockify API key (profile settings)

Install

# via npx
npx @lewinnovation/clockify-mcp-server

# OR via pnpm globally
pnpm add -g @lewinnovation/clockify-mcp-server

# OR clone and install locally
pnpm install
pnpm run build

Configuration

| Variable | Required | Description | |----------|----------|-------------| | CLOCKIFY_API_KEY | Yes | Sent as X-Api-Key on every request. | | CLOCKIFY_API_BASE_URL | No | Defaults to https://api.clockify.me/api. Override only if Clockify documents a different base for your account or region. |

Run (stdio)

The server speaks MCP over stdio (stdout must stay clean JSON-RPC; logs go to stderr).

export CLOCKIFY_API_KEY="your-key"
pnpm start

Or after pnpm run build:

node dist/index.js

MCP tool handlers are registered from src/tools/register.ts (shared helpers in src/tools/helpers.ts).

MCP client setup (popular AI agent tools)

Use this server definition in your MCP client:

{
  "mcpServers": {
    "clockify": {
      "command": "npx",
      "args": ["-y", "@lewinnovation/clockify-mcp-server"],
      "env": {
        "CLOCKIFY_API_KEY": "your-key"
      }
    }
  }
}

If you prefer running a local clone, use:

{
  "mcpServers": {
    "clockify": {
      "command": "node",
      "args": ["/absolute/path/to/clockify-mcp-server/dist/index.js"],
      "env": {
        "CLOCKIFY_API_KEY": "your-key"
      }
    }
  }
}

Cursor

Add the JSON entry above to:

• Workspace config: .cursor/mcp.json
• Or user config: ~/.cursor/mcp.json

Then reload Cursor (or restart the MCP server from Cursor settings).

Claude Desktop

Add the same mcpServers.clockify entry to Claude Desktop MCP config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop after saving the config.

Claude Code (CLI)

From your project directory:

claude mcp add clockify --env CLOCKIFY_API_KEY=your-key -- npx -y @lewinnovation/clockify-mcp-server

Or add the same JSON server entry to your Claude Code MCP config file if you manage MCP servers declaratively.

Other MCP-compatible agent tools

For tools such as Cline, Roo Code, and Windsurf, add the same server command/env block in that tool's MCP server settings UI or config file:

• command: npx
• args: ["-y", "@lewinnovation/clockify-mcp-server"]
• env.CLOCKIFY_API_KEY: your Clockify API key

The server uses stdio transport, so no host/port configuration is required.

Tools

Curated

• get_current_user — GET /v1/user
• list_workspaces — GET /v1/workspaces (optional single role filter; multiple roles require clockify_request)
• list_projects — GET /v1/workspaces/{workspaceId}/projects with pagination (page, page_size → page-size)
• list_tasks — GET /v1/workspaces/{workspaceId}/projects/{projectId}/tasks
• list_time_entries — GET /v1/workspaces/{workspaceId}/user/{userId}/time-entries (if user_id is omitted, the current API user is resolved via GET /v1/user)
• create_time_entry — POST /v1/workspaces/{workspaceId}/time-entries
• update_time_entry — PUT /v1/workspaces/{workspaceId}/time-entries/{id} (Clockify requires start on updates)
• stop_running_time_entry — PATCH /v1/workspaces/{workspaceId}/user/{userId}/time-entries with { end } (optional user_id, default current user)

Generic

• clockify_request — method, path (must start with /v1/), optional query map, optional JSON body (max 256 KiB serialized). Array query values are sent as repeated keys.

Responses wrap JSON in a text content block; when Clockify returns a Last-Page header, curated list-style tools include lastPage in the decoded JSON payload.

OpenAPI types

Types are generated from Clockify’s OpenAPI document:

pnpm run generate:openapi

Source URL: https://api.clockify.me/api/v3/api-docs
Output: src/generated/clockify.d.ts

Re-run this periodically to pick up API changes, then fix any compile errors from type drift.

Scripts

| Script | Purpose | |--------|---------| | pnpm run dev | Watch src/index.ts with tsx. | | pnpm run build | Emit dist/ with tsc. | | pnpm run typecheck | tsc --noEmit. | | pnpm run smoke | Mocked HTTP smoke test for curated endpoints (no API key needed; uses a dummy key + mocked fetch). | | pnpm run generate:openapi | Regenerate src/generated/clockify.d.ts. |

License

MIT