Clockify MCP Server

A local MCP (Model Context Protocol) server that lets you manage your Clockify timesheets directly from any AI assistant that supports the protocol — add entries, remove entries, browse projects, and more.

Features

Add time entries — Log hours to any project with description, start/end times, and optional billing flag.
Delete time entries — Remove incorrect or duplicate entries by ID.
Browse timesheets — Query your time entries with optional date-range filters.
List workspaces & projects — Discover available workspaces and their active projects.
Identify yourself — Retrieve your user ID and default workspace in one call.
Stdio transport — Runs locally as a child process; no HTTP server or open ports needed.

Prerequisites

Node.js ≥ 18 (uses native fetch)
npm ≥ 9
A Clockify account with an API key

Installation

# 1. Clone or navigate to this directory
cd /path/to/ClokifyMCP        # macOS / Linux
cd C:\path\to\ClokifyMCP       # Windows

# 2. Install dependencies
npm install

# 3. Build the TypeScript source
npm run build

The compiled server is output to dist/index.js.

Note: In the configuration examples below, replace /path/to/ClokifyMCP (macOS/Linux) or C:\\path\\to\\ClokifyMCP (Windows) with the actual absolute path where you cloned this repository.

Configuration

Get your Clockify API Key

Log in to Clockify.
Go to Profile Settings → Advanced (direct link).
Click Generate to create a new API key.
Copy the key — you will provide it as the CLOCKIFY_API_KEY environment variable.

Windsurf / Cascade

Edit the MCP config file for your platform:

Platform	Config file path
macOS / Linux	`~/.codeium/windsurf/mcp_config.json`
Windows	`%USERPROFILE%\.codeium\windsurf\mcp_config.json`

macOS / Linux:

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

Windows:

{
  "mcpServers": {
    "clockify": {
      "command": "node",
      "args": ["C:\\path\\to\\ClokifyMCP\\dist\\index.js"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Windsurf after saving.

Claude Desktop

Edit the config file for your platform:

Platform	Config file path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

macOS / Linux:

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

Windows:

{
  "mcpServers": {
    "clockify": {
      "command": "node",
      "args": ["C:\\path\\to\\ClokifyMCP\\dist\\index.js"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root or global config:

macOS / Linux:

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

Windows:

{
  "mcpServers": {
    "clockify": {
      "command": "node",
      "args": ["C:\\path\\to\\ClokifyMCP\\dist\\index.js"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client that supports stdio transport can use this server. The configuration pattern is always the same:

Setting	macOS / Linux	Windows
Command	`node`	`node`
Args	`["/path/to/ClokifyMCP/dist/index.js"]`	`["C:\\path\\to\\ClokifyMCP\\dist\\index.js"]`
Env	`CLOCKIFY_API_KEY=<your-key>`	`CLOCKIFY_API_KEY=<your-key>`

Available Tools

`get_current_user`

Returns the authenticated Clockify user profile.

Parameter	Type	Required	Description
(none)	—	—	No parameters needed

Response fields: id, name, email, activeWorkspace, defaultWorkspace

Use this first to obtain your userId and activeWorkspace — both are required by other tools.

`get_workspaces`

Lists all workspaces the user has access to.

Parameter	Type	Required	Description
(none)	—	—	No parameters needed

Response fields per workspace: id, name

`get_projects`

Lists all active (non-archived) projects in a workspace.

Parameter	Type	Required	Description
`workspaceId`	`string`	Yes	The workspace ID

Response fields per project: id, name, clientName, color, archived

`get_time_entries`

Fetches time entries for a specific user in a workspace, with optional date filtering.

Parameter	Type	Required	Description
`workspaceId`	`string`	Yes	The workspace ID
`userId`	`string`	Yes	The user ID (from `get_current_user`)
`start`	`string`	No	Start date in ISO 8601 (e.g. `2025-03-01T00:00:00Z`)
`end`	`string`	No	End date in ISO 8601 (e.g. `2025-03-31T23:59:59Z`)

Response fields per entry: id, description, projectId, timeInterval (start, end, duration), billable, taskId, tagIds

Returns up to 50 entries per call, ordered newest-first.

`add_time_entry`

Creates a new time entry on the workspace timesheet.

Parameter	Type	Required	Description
`workspaceId`	`string`	Yes	The workspace ID
`start`	`string`	Yes	Start time in ISO 8601 (e.g. `2025-03-28T09:00:00Z`)
`end`	`string`	No	End time in ISO 8601. Omit to start a running timer.
`description`	`string`	No	Description of the work performed
`projectId`	`string`	No	Project ID to assign the entry to
`billable`	`boolean`	No	Whether the entry is billable (default: `false`)
`taskId`	`string`	No	Task ID within the project
`tagIds`	`string[]`	No	Array of tag IDs to attach

Returns: The newly created time entry object.

`delete_time_entry`

Deletes a time entry from the workspace timesheet.

Parameter	Type	Required	Description
`workspaceId`	`string`	Yes	The workspace ID
`timeEntryId`	`string`	Yes	The ID of the time entry to delete

Returns: Confirmation message on success.

Usage Examples

Below are natural-language prompts you can give your AI assistant once the MCP server is connected:

Find your user info

"Get my Clockify user info"

List your projects

"Show me all the projects in my Clockify workspace"

Log 8 hours of work

"Add a time entry for today from 9am to 5pm on project X with description 'Sprint planning'"

Check this week's timesheet

"Show me all my time entries from this week"

Remove a wrong entry

"Delete time entry abc123 from my workspace"

Full day logging workflow

"Log 8 hours today on the Accelya project: 9am–12pm 'Backend API development', 1pm–5pm 'Code review and testing'"

Project Structure

ClokifyMCP/
├── src/
│   ├── index.ts              # MCP server — tool definitions & stdio transport
│   └── clockify-client.ts    # Typed HTTP client for the Clockify REST API v1
├── dist/                     # Compiled JavaScript output (after build)
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md

Architecture

┌──────────────┐   stdio    ┌──────────────────┐   HTTPS    ┌───────────────┐
│  MCP Client  │◄─────────►│  MCP Server       │──────────►│  Clockify API │
│  (Windsurf,  │            │  (src/index.ts)   │           │  api.clockify │
│   Claude…)   │            │                   │           │  .me/api/v1   │
└──────────────┘            │  ClockifyClient   │           └───────────────┘
                            │  (clockify-       │
                            │   client.ts)      │
                            └──────────────────┘

Transport: stdio (JSON-RPC over stdin/stdout)
Auth: Clockify API key passed via CLOCKIFY_API_KEY environment variable
API base URL: https://api.clockify.me/api/v1

Development

Run in development mode (no build step)

macOS / Linux (bash/zsh):

CLOCKIFY_API_KEY=your-key npm run dev

Windows (PowerShell):

$env:CLOCKIFY_API_KEY="your-key"; npm run dev

Windows (Command Prompt):

set CLOCKIFY_API_KEY=your-key && npm run dev

Build for production

npm run build

Start the compiled server

macOS / Linux (bash/zsh):

CLOCKIFY_API_KEY=your-key npm start

Windows (PowerShell):

$env:CLOCKIFY_API_KEY="your-key"; npm start

Windows (Command Prompt):

set CLOCKIFY_API_KEY=your-key && npm start

Available npm scripts

Script	Command	Description
`build`	`tsc`	Compile TypeScript to `dist/`
`start`	`node dist/index.js`	Run the compiled server
`dev`	`tsx src/index.ts`	Run directly from TypeScript (no build needed)

Dependencies

Package	Purpose
`@modelcontextprotocol/sdk`	MCP server framework + Zod for tool schemas
`typescript`	TypeScript compiler (dev)
`tsx`	TypeScript runner for development (dev)
`@types/node`	Node.js type definitions (dev)

Troubleshooting

"CLOCKIFY_API_KEY environment variable is required"

The server requires the CLOCKIFY_API_KEY env var. Make sure it is set in your MCP client configuration under the "env" block.

"Clockify API error 401"

Your API key is invalid or expired. Generate a new one from Clockify Settings.

"Clockify API error 403"

You don't have permission to perform this action in the workspace. Check your Clockify role and workspace access.

"Clockify API error 404"

The workspace ID, project ID, user ID, or time entry ID you provided does not exist. Use get_current_user and get_workspaces to discover valid IDs.

Server not showing up in MCP client

Verify the dist/index.js file exists (run npm run build if not).
Check the path in your MCP config is absolute and correct.
Restart your MCP client after editing the config file.

Type errors during build

Run npm install to ensure all dependencies are installed, then npm run build.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Clockify MCP Server

Table of Contents

Features

Prerequisites

Installation

Configuration

Get your Clockify API Key

Windsurf / Cascade

Claude Desktop

Cursor

Other MCP Clients

Available Tools

get_current_user

get_workspaces

get_projects

get_time_entries

add_time_entry

delete_time_entry

Usage Examples

Find your user info

List your projects

Log 8 hours of work

Check this week's timesheet

Remove a wrong entry

Full day logging workflow

Project Structure

Architecture

Development

Run in development mode (no build step)

Build for production

Start the compiled server

Available npm scripts

Dependencies

Troubleshooting

"CLOCKIFY_API_KEY environment variable is required"

"Clockify API error 401"

"Clockify API error 403"

"Clockify API error 404"

Server not showing up in MCP client

Type errors during build

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`get_current_user`

`get_workspaces`

`get_projects`

`get_time_entries`

`add_time_entry`

`delete_time_entry`