Clockify Master MCP

The Ultimate Clockify Integration for Claude Desktop

Transform how you track time by bringing Clockify's powerful time management capabilities directly into your Claude conversations. Start timers, create projects, generate reports, and manage your entire workflow without switching apps.

🚀 Quick Start

1. Get Your API Key

Visit Clockify Settings → API section → Copy your API Key

2. Install & Configure

Add this to your Claude Desktop MCP settings (claude_desktop_config.json):

{
  "mcpServers": {
    "clockify": {
      "command": "npx",
      "args": ["@hongkongkiwi/clockify-master-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}

3. Restart Claude Desktop

That's it! You can now ask Claude to track time, create projects, generate reports, and more.

✨ What You Can Do

📊 Time Tracking Made Simple

"Start tracking time for project setup" - Instantly begin time tracking
"What's my running timer?" - Check active timers
"Stop my current timer" - End time tracking
"Show me today's time entries" - Review your daily activity

📈 Project & Client Management

"Create a new project called 'Website Redesign'" - Set up projects quickly
"List all my active projects" - See your project portfolio
"Add a client named 'Acme Corp'" - Manage client relationships
"Archive the old marketing project" - Keep workspace organized

📋 Task Organization

"Create tasks for the mobile app project" - Break down work into tasks
"Mark the design task as complete" - Track progress
"Show tasks assigned to John" - Monitor team assignments

📊 Powerful Reporting

"Generate a weekly time report" - Get detailed summaries
"Show team productivity for last month" - Analyze team performance
"Export project report as CSV" - Share insights with stakeholders
"How much time did I spend on client work?" - Track billable hours

🏷️ Smart Organization

"Tag this entry as 'meeting'" - Categorize activities
"Create tags for different project phases" - Organize workflows
"Find all entries tagged 'research'" - Locate specific work

🎯 Popular Use Cases

Freelancers & Consultants

{
  "mcpServers": {
    "clockify-freelancer": {
      "command": "npx",
      "args": ["@hongkongkiwi/clockify-master-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here",
        "ENABLED_TOOL_CATEGORIES": "user,workspace,project,client,timeEntry,report",
        "MAX_TOOLS": "20"
      }
    }
  }
}

Perfect for: Client billing, project tracking, detailed reporting

Team Managers

{
  "mcpServers": {
    "clockify-team": {
      "command": "npx",
      "args": ["@hongkongkiwi/clockify-master-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here",
        "ALLOWED_PROJECTS": "proj-123,proj-456",
        "ENABLED_TOOL_CATEGORIES": "user,workspace,project,timeEntry,task,report",
        "READ_ONLY": "false",
        "MAX_TOOLS": "25"
      }
    }
  }
}

Perfect for: Team oversight, project management, productivity analysis

Simple Time Tracking

{
  "mcpServers": {
    "clockify-simple": {
      "command": "npx",
      "args": ["@hongkongkiwi/clockify-master-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here",
        "ENABLED_TOOLS": "get_current_user,create_time_entry,stop_timer,get_today_entries,get_summary_report",
        "MAX_TOOLS": "5"
      }
    }
  }
}

Perfect for: Personal productivity, basic time tracking, minimal setup

Analytics & Reporting Only

{
  "mcpServers": {
    "clockify-reports": {
      "command": "npx",
      "args": ["@hongkongkiwi/clockify-master-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here",
        "ENABLED_TOOL_CATEGORIES": "user,workspace,project,report",
        "READ_ONLY": "true",
        "MAX_TOOLS": "12"
      }
    }
  }
}

Perfect for: Executives, analysts, report generation without data modification

🔧 Customization Options

Choose Your Tools

Control which features are available to avoid overwhelming Claude:

All Features (38 tools): Complete Clockify integration
Time Tracking Focus (12 tools): Essential time management
Project Management (18 tools): Full project control
Reporting Only (10 tools): Analytics and insights
Minimal Setup (5 tools): Just the basics

Set Boundaries

Restrict access to specific projects or workspaces:

# Only work with specific projects
ALLOWED_PROJECTS=website-redesign,mobile-app,marketing-campaign

# Default workspace for all operations
DEFAULT_WORKSPACE_ID=your-main-workspace-id

# Prevent accidental deletions
READ_ONLY=false
ALLOW_TIME_ENTRY_DELETION=false

Smart Filtering

# Focus on essential categories
ENABLED_TOOL_CATEGORIES=user,workspace,timeEntry,report

# Exclude specific tools you don't need
DISABLED_TOOLS=bulk_edit_time_entries,delete_time_entry

# Limit total tools (helps with Claude's tool limits)
MAX_TOOLS=15

🛡️ Project Configuration Protections

When you configure specific projects (using DEFAULT_PROJECT_ID or ALLOWED_PROJECTS), the system automatically protects these projects from accidental damage:

🚫 Blocked Operations

These operations are completely prevented when they would affect your configured projects:

delete_project - Cannot delete configured projects
archive_project - Cannot archive configured projects
remove_user_from_project - Cannot remove users from configured projects
delete_client - Cannot delete clients that configured projects depend on
delete_task - Cannot delete tasks from configured projects
delete_workspace - Cannot delete workspaces containing configured projects
bulk_edit_time_entries - Cannot bulk-assign time entries TO configured projects

⚠️ Protected Operations with Warnings

These operations are allowed but generate warnings:

update_project - Warns when changing critical fields (name, client)
update_workspace - Warns about settings that could affect project functionality
delete_tag - Warns when deleting tags from workspaces with configured projects
bulk_edit_time_entries - Warns when bulk operations might affect configured projects

✅ Enhanced Operations

These operations are automatically improved:

update_time_entry - Automatically preserves existing project assignments to prevent validation errors

Configuration Examples

Protect a specific default project:

{
  "env": {
    "CLOCKIFY_API_KEY": "your_api_key_here",
    "DEFAULT_PROJECT_ID": "project-12345",
    "DEFAULT_WORKSPACE_ID": "workspace-67890"
  }
}

Restrict to only specific projects:

{
  "env": {
    "CLOCKIFY_API_KEY": "your_api_key_here",
    "ALLOWED_PROJECTS": "proj-123,proj-456,proj-789"
  }
}

Error Messages You Might See

"Cannot delete the configured default project. Please update your configuration first."
"Cannot remove users from a configured project. This could break access to required project functionality."
"Cannot delete client: The following configured projects depend on this client: Website Project, Mobile App."

These protections ensure your critical project configurations remain intact while still allowing full functionality for non-configured projects.

💡 Real Usage Examples

Starting Your Day

You: "Start tracking time for the morning standup meeting"

Claude: Using Clockify, I'll start tracking time for your standup meeting... ✅ Timer started for "Morning standup meeting" ⏰ Started at 9:00 AM 📁 Project: Team Management

Checking Progress

You: "What did I work on yesterday and for how long?"

Claude: Here's your time summary for yesterday:

Website Development: 6.5 hours
- Frontend updates: 3.5h
- Bug fixes: 2h
- Code review: 1h
Client Meetings: 1.5 hours
Admin Tasks: 0.5 hours Total: 8.5 hours

Project Planning

You: "Create a new project for the Q2 marketing campaign with tasks for planning, design, and execution"

Claude: I've created your Q2 marketing campaign project with these tasks: ✅ Project Created: "Q2 Marketing Campaign" 📋 Tasks Added:

Campaign Planning (assigned to you)
Creative Design (ready for assignment)
Campaign Execution (ready for assignment)

Weekly Reporting

You: "Generate a weekly report showing time by project and export it as CSV"

Claude: Here's your weekly time report:

Total Hours: 42.5
Most Active Project: Website Development (28h)
Billable Hours: 38.5h
Non-billable: 4h

📊 CSV export ready - Contains detailed breakdown by day and project

🛠️ Installation Methods

Option 1: NPX (Recommended)

{
  "command": "npx",
  "args": ["@hongkongkiwi/clockify-master-mcp"]
}

✅ Always latest version
✅ No local installation needed
✅ Automatic updates

Option 2: Local Installation

npm install -g @hongkongkiwi/clockify-master-mcp

{
  "command": "clockify-master-mcp"
}

✅ Faster startup
✅ Works offline
✅ Version control

Option 3: Development Setup

git clone https://github.com/hongkongkiwi/mcp-clockify.git
cd mcp-clockify
npm install
npm run build

{
  "command": "node",
  "args": ["path/to/mcp-clockify/dist/index.js"]
}

✅ Latest features
✅ Customizable
✅ Contribute back

🎨 Tool Categories Explained

🙋 User Tools (4 total)

Get information about yourself and team members

Who am I? What's my current workspace?
List team members and find colleagues
Get user details and contact information

🏢 Workspace Tools (2 total)

Manage your Clockify workspaces

Switch between workspaces
View workspace settings and details
See available workspaces

📁 Project Tools (6 total)

Complete project lifecycle management

Create, update, and organize projects
Archive completed projects
Search and filter project lists
Associate projects with clients

👥 Client Tools (4 total)

Manage your client relationships

Add new clients with contact details
Update client information
Track which projects belong to which clients
Archive inactive clients

⏱️ Time Entry Tools (9 total)

Full-featured time tracking

Start/stop timers with descriptions
Create historical time entries
Edit and delete existing entries
Get entries by day, week, or month
Bulk operations for efficiency

📋 Task Tools (4 total)

Break down projects into manageable tasks

Create tasks within projects
Assign tasks to team members
Track task completion
Set time estimates

🏷️ Tag Tools (3 total)

Organize and categorize your work

Create custom tags for activities
Apply tags to time entries
Bulk create multiple tags
Filter and search by tags

📊 Report Tools (5 total)

Powerful analytics and insights

Generate summary reports
Track user and team productivity
Monitor project progress
Export data in multiple formats
Customizable date ranges and filters

⚡ Bulk Tools (1 total)

Efficient mass operations

Edit multiple time entries at once
Delete multiple entries
Update project assignments in bulk

🔍 Search Tools (2 total)

Find anything quickly

Search projects by name
Find users by name or role
Filter results efficiently

🚨 Troubleshooting

Claude can't see Clockify tools

Check your claude_desktop_config.json file location
Restart Claude Desktop completely
Verify your API key is correct
Check that the MCP server name doesn't conflict with others

"Invalid API key" errors

Generate a new API key at Clockify Settings
Make sure there are no extra spaces in your API key
Check that your account has the necessary permissions

"Too many tools" warning

Use tool filtering to reduce the number of exposed tools:

"ENABLED_TOOL_CATEGORIES": "user,workspace,timeEntry"
"MAX_TOOLS": "10"

"Access denied" to projects/workspaces

You might have restrictions configured. Check for these settings:

ALLOWED_PROJECTS=project-id-1,project-id-2
ALLOWED_WORKSPACES=workspace-id

Time entries not showing up

Check if you're looking in the correct workspace
Verify date ranges (some tools filter by date)
Ensure you have access to the specific project

"Cannot delete/archive configured project" errors

These are protection features working as intended. When you configure specific projects (DEFAULT_PROJECT_ID or ALLOWED_PROJECTS), the system prevents accidental damage:

To delete a configured project: Remove it from your environment configuration first
To archive a configured project: Update your configuration to remove the restriction
To delete clients/tasks: Check if they're used by configured projects

Example fix:

{
  "env": {
    "CLOCKIFY_API_KEY": "your_api_key_here"
    // Remove or change this line to allow deletion:
    // "DEFAULT_PROJECT_ID": "project-12345"
  }
}

📋 Environment Variables Reference

Required

CLOCKIFY_API_KEY - Your Clockify API key (required)

Regional Settings

CLOCKIFY_REGION - API region (global, eu, us) - default: global
CLOCKIFY_API_URL - Custom API URL (overrides region setting)

Project Protection Settings

DEFAULT_PROJECT_ID - Default project ID (enables protection for this project)
DEFAULT_WORKSPACE_ID - Default workspace ID (enables protection for this workspace)
ALLOWED_PROJECTS - Comma-separated list of allowed project IDs (enables protection)
ALLOWED_WORKSPACES - Comma-separated list of allowed workspace IDs

Tool Filtering

ENABLED_TOOL_CATEGORIES - Comma-separated categories: user,workspace,project,client,timeEntry,tag,task,report,bulk,search,customField
ENABLED_TOOLS - Comma-separated specific tool names
DISABLED_TOOLS - Comma-separated tools to exclude
MAX_TOOLS - Maximum number of tools to expose (default: unlimited)

Operation Restrictions

READ_ONLY - Set to true to prevent all write operations
ALLOW_TIME_ENTRY_CREATION - Allow creating time entries (default: true)
ALLOW_TIME_ENTRY_DELETION - Allow deleting time entries (default: true)
ALLOW_PROJECT_MANAGEMENT - Allow project operations (default: true)
ALLOW_CLIENT_MANAGEMENT - Allow client operations (default: true)
ALLOW_USER_MANAGEMENT - Allow user operations (default: false)

Time Entry Restrictions

ALLOW_FUTURE_TIME_ENTRIES - Allow future time entries (default: false)
ALLOW_PAST_TIME_ENTRIES_IN_DAYS - Days back to allow time entries (default: 30)
MAX_TIME_ENTRY_DURATION - Maximum hours per time entry

Performance & Caching

CACHE_ENABLED - Enable response caching (default: false)
CACHE_TTL - Cache time-to-live in seconds
RATE_LIMIT - Requests per minute limit
LOG_LEVEL - Logging level (debug, info, warn, error)

Complete Example

{
  "env": {
    "CLOCKIFY_API_KEY": "your_api_key_here",
    "CLOCKIFY_REGION": "eu",
    "DEFAULT_PROJECT_ID": "project-12345",
    "DEFAULT_WORKSPACE_ID": "workspace-67890",
    "ENABLED_TOOL_CATEGORIES": "user,workspace,timeEntry,project,report",
    "MAX_TOOLS": "20",
    "ALLOW_PAST_TIME_ENTRIES_IN_DAYS": "90",
    "CACHE_ENABLED": "true",
    "LOG_LEVEL": "info"
  }
}

🤝 Support & Community

Issues & Bugs: GitHub Issues
Feature Requests: Open a GitHub issue with the "enhancement" label
Questions: Use GitHub Discussions
Clockify API: Official Documentation

📄 License

MIT License - Feel free to use, modify, and distribute.

Ready to supercharge your time tracking? Add Clockify Master MCP to Claude Desktop and start managing your time more efficiently today! 🚀

🔄 Publishing Status

This package is published to both NPM and JSR registries:

NPM: @hongkongkiwi/clockify-master-mcp
JSR: @hongkongkiwi/clockify-master-mcp

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Integrates Clockify time tracking directly into Claude Desktop, enabling users to start/stop timers, manage projects and clients, create tasks, generate reports, and track productivity through natural language commands.

Related MCP Servers

Things MCP Server
hald
A
security
A
license
A
quality
Enables interaction with the Things app through Claude Desktop, allowing task creation, project analysis, and priority management using natural language commands.
Last updated -
22
104
Python
MIT License
Todoist MCP Server
Chrusic
A
security
A
license
A
quality
Integrates Claude with Todoist for natural language task management, supporting project and section organization, task creation, updating, completion, and deletion using everyday language.
Last updated -
19
8
18
JavaScript
MIT License
Things MCP Server
excelsier
-
security
F
license
-
quality
Lets you use Claude Desktop to interact with your task management data in Things app, enabling you to create tasks, analyze projects, manage priorities, and implement productivity workflows through natural language.
Last updated -
26
Python
MCP Claude Spotify
imprvhub
A
security
A
license
A
quality
An integration that allows Claude Desktop to interact with Spotify, enabling users to control playback, search music, manage playlists, and get recommendations through natural language commands.
Last updated -
12
17
TypeScript
Mozilla Public License 2.0

View all related MCP servers