Clockify MCP Server
Provides tools for interacting with the Clockify API to manage time entries, start and stop timers, and perform team management tasks like analyzing weekly summaries and identifying overtime or undertime users.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Clockify MCP Server Show me all time logged to the 'Website Redesign' project this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WARNING
β οΈ THIS HAS MOSTLY BEEN CODED VIA AI - PROCEED AT YOUR OWN RISKβ οΈ
Clockify MCP Server
A Model Context Protocol (MCP) server that provides seamless integration with the Clockify time tracking API. This server enables AI assistants to interact with Clockify for time tracking, reporting, and team management tasks.
Features
Core Functionality
π Find time entries by user, project, or search phrase
β±οΈ Start and stop timers with project association
β Add time entries for any user with flexible parameters
π High-level analysis tools for team management
π Weekly summaries and overtime detection
High-Level Tools
Find overtime users: Identify team members working >40 hours/week
Find undertime users: Identify team members logging <20 hours/week
Weekly summaries: Get detailed breakdowns of hours by week
Project analytics: See who's working on what and for how long
Related MCP server: Clockify MCP Server
Installation
Prerequisites
Python 3.10 or higher
Clockify API key (Get one here)
Quick Install with uvx
The easiest way to use this server is with uvx (bundled with uv):
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Run the server directly (it will be cached)
uvx clockify-mcp-serverManual Installation
# Clone the repository
git clone https://github.com/yourusername/clockify-mcp-server.git
cd clockify-mcp-server
# Install with pip
pip install -e .
# Or install from PyPI (once published)
pip install clockify-mcp-serverConfiguration
Environment Variables
Set your Clockify API key as an environment variable:
export CLOCKIFY_API_KEY="your_api_key_here"You can get your API key from Clockify User Settings under "API" section.
MCP Client Configuration
Add this to your MCP client configuration file:
For Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"clockify": {
"command": "uvx",
"args": ["clockify-mcp-server"],
"env": {
"CLOCKIFY_API_KEY": "your_api_key_here"
}
}
}
}For Opencode
{
"mcp": {
"clockify": {
"command": ["uvx", "clockify-mcp-server"]
"environment": {
"CLOCKIFY_API_KEY": "your_api_key_here"
}
}
}
}Available Tools
1. find_user_time_entries
Find all time entries for a specific user.
Parameters:
user_name(required): Name of the user (partial match, case-insensitive)start_date(optional): Start date in YYYY-MM-DD format (default: 30 days ago)end_date(optional): End date in YYYY-MM-DD format (default: today)limit(optional): Maximum entries to display (default: 50, use 0 for unlimited)workspace_id(optional): Workspace ID (default: user's default workspace)
Example:
Find all time entries for John Doe from the last 30 days2. find_project_time_entries
Find all time entries for a specific project.
Parameters:
project_name(required): Name of the project (partial match, case-insensitive)start_date(optional): Start date in YYYY-MM-DD format (default: 30 days ago)end_date(optional): End date in YYYY-MM-DD format (default: today)limit(optional): Maximum entries to display (default: 30, use 0 for unlimited)workspace_id(optional): Workspace ID
Example:
Show me all time logged to the "Website Redesign" project this month3. search_time_entries
Search time entries by description phrase.
Parameters:
search_phrase(required): Phrase to search for in descriptionsuser_name(optional): Limit search to specific userstart_date(optional): Start date in YYYY-MM-DD format (default: 30 days ago)end_date(optional): End date in YYYY-MM-DD format (default: today)limit(optional): Maximum entries to display (default: 50, use 0 for unlimited)workspace_id(optional): Workspace ID
Example:
Find all time entries containing "meeting" in the description4. add_time_entry
Add a time entry for a specific user.
Parameters:
user_name(required): Name of the userdescription(required): Description of the workstart_time(required): Start time in ISO format (e.g., 2024-01-29T09:00:00)end_time(required): End time in ISO format (e.g., 2024-01-29T17:00:00)project_name(optional): Project to associate withtask_name(optional): Task within the project (requires project_name)billable(optional): Whether time is billable (default: true)workspace_id(optional): Workspace ID
Example:
Add a time entry for Jane Smith: 8 hours today on "Client Project" for meetings5. start_timer
Start a timer for the current user.
Parameters:
description(required): What you're working onproject_name(optional): Project to associate withtask_name(optional): Task within the project (requires project_name)workspace_id(optional): Workspace ID
Example:
Start a timer for "Writing documentation" on the "Internal Tools" project6. stop_timer
Stop the currently running timer.
Parameters:
workspace_id(optional): Workspace ID
Example:
Stop my current timer7. find_overtime_users
Find users working more than specified hours per week.
Parameters:
hours_threshold(optional): Hours per week threshold (default: 40)weeks(optional): Number of weeks to analyze (default: 4)workspace_id(optional): Workspace ID
Example:
Show me team members who worked more than 40 hours in any week this month8. find_undertime_users
Find users who didn't log minimum hours per week.
Parameters:
hours_threshold(optional): Minimum hours threshold (default: 20)weeks(optional): Number of weeks to analyze (default: 1)workspace_id(optional): Workspace ID
Example:
Who didn't log at least 20 hours last week?9. get_user_weekly_summary
Get a weekly breakdown of hours for a user.
Parameters:
user_name(required): Name of the userweeks(optional): Number of weeks to analyze (default: 4)workspace_id(optional): Workspace ID
Example:
Show me John's weekly hours for the past monthUsage Examples
With Claude Desktop
Once configured, you can ask Claude natural language questions:
"Find all time entries for Sarah Johnson from last week"
"Show me everyone who logged time to the Mobile App project this month"
"Start a timer for code review on the Backend API project"
"Who on the team worked more than 45 hours in the past month?"
"Add a time entry for Mike: 4 hours yesterday on Client Presentation"Programmatic Usage
from clockify_mcp import ClockifyClient
import asyncio
async def main():
client = ClockifyClient(api_key="your_api_key")
# Get current user
user = await client.get_current_user()
print(f"Logged in as: {user['name']}")
# Get default workspace
workspace = await client.get_default_workspace()
# Find a user
user = await client.find_user_by_name(workspace['id'], "John")
# Get their time entries
entries = await client.get_time_entries(
workspace_id=workspace['id'],
user_id=user['id']
)
print(f"Found {len(entries)} time entries")
await client.close()
asyncio.run(main())Development
Setup Development Environment
# Clone the repository
git clone https://github.com/KeithHanson/clockify-mcp
cd clockify-mcp-server
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"Running Tests
pytest tests/Code Formatting
# Format code
black src/
# Lint code
ruff check src/Project Structure
clockify-mcp-server/
βββ src/
β βββ clockify_mcp/
β βββ __init__.py
β βββ client.py # Clockify API client
β βββ server.py # MCP server implementation
βββ docs/ # Full API documentation
β βββ 00_INDEX.md
β βββ 01_USER_API.md
β βββ 02_WORKSPACE_API.md
β βββ 03_TIME_ENTRY_API.md
β βββ 04_PROJECT_API.md
β βββ 05_REPORTS_API.md
β βββ 06_WEBHOOKS_API.md
β βββ 07_QUICK_REFERENCE.md
βββ tests/ # Test suite
βββ pyproject.toml # Project configuration
βββ README.md # This file
βββ LICENSE # MIT LicenseAPI Documentation
Complete API documentation is available in the docs/ directory:
00_INDEX.md - Overview and quick reference
01_USER_API.md - User management endpoints
02_WORKSPACE_API.md - Workspace configuration
03_TIME_ENTRY_API.md - Time tracking operations
04_PROJECT_API.md - Project management
05_REPORTS_API.md - Reporting and analytics
06_WEBHOOKS_API.md - Webhook configuration (not implemented in MCP server)
07_QUICK_REFERENCE.md - Code snippets and examples
Limitations
User-specific operations: Some operations (like adding time entries for other users) may require workspace admin permissions
Rate limiting: The server respects Clockify's rate limits (50 requests/second for addon tokens)
Workspace selection: Defaults to user's default workspace if not specified
Webhooks: Not implemented (not needed for MCP use case)
Troubleshooting
"CLOCKIFY_API_KEY environment variable is required"
Make sure you've set the API key in your environment or MCP configuration:
export CLOCKIFY_API_KEY="your_key_here""User not found"
User names are matched using partial, case-insensitive search. Try:
Using just the first or last name
Checking spelling
Using the email address instead
"No workspaces found"
Ensure your API key is valid and you have access to at least one workspace in Clockify.
Connection Issues
If you're having connection issues:
Check your internet connection
Verify your API key is correct
Ensure you're not behind a proxy that blocks API requests
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
License
MIT License - see LICENSE file for details
Acknowledgments
Built on the Model Context Protocol
Integrates with Clockify time tracking
Documentation derived from official Clockify API docs
Support
Issues: GitHub Issues
Discussions: GitHub Discussions
Clockify API: docs.clockify.me
Changelog
v0.1.0 (Initial Release)
Core time entry operations
User and project search
Timer start/stop functionality
High-level analysis tools
Overtime/undertime detection
Weekly summaries
Available Tools
9 toolsadd_time_entryC
Add a time entry for a specific user. Creates a completed time entry with start and end times.
Inputs: user_name (required), description (required), start_time (required), end_time (required), +4 more.
find_overtime_usersB
Find users who have logged more than a specified number of hours per week in the past month. Useful for identifying overworked team members.
Inputs: hours_threshold, weeks, workspace_id.
find_project_time_entriesA
Find all time entries for a specific project. Returns time entries from all users who have logged time to the project.
Inputs: project_name (required), start_date, end_date, limit, +1 more.
find_undertime_usersB
Find users who have not logged at least a specified number of hours per week. Useful for identifying team members who may need support.
Inputs: hours_threshold, weeks, workspace_id.
find_user_time_entriesA
Find all time entries for a specific user by their name. Searches across a date range (defaults to last 30 days) and returns all time entries with descriptions, projects, and durations.
Inputs: user_name (required), start_date, end_date, limit, +1 more.
get_user_weekly_summaryC
Get a summary of hours logged by a user for each week in the past month.
Inputs: user_name (required), weeks, workspace_id.
search_time_entriesA
Search time entries by description phrase. Searches across all users and returns entries containing the search phrase.
Inputs: search_phrase (required), user_name, start_date, end_date, +2 more.
start_timerC
Start a timer for the current user. Creates a running time entry without an end time.
Inputs: description (required), project_name, task_name, workspace_id.
stop_timerB
Stop the currently running timer for the current user.
Inputs: workspace_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 9 tools
Each tool has a clearly distinct purpose with no overlap: adding entries, starting/stopping timers, finding entries by project/user/search, identifying overtime/undertime users, and getting weekly summaries. The descriptions make it easy to differentiate between similar-sounding tools like find_user_time_entries and get_user_weekly_summary.
All tools follow a consistent snake_case pattern with clear verb_noun combinations (e.g., add_time_entry, find_project_time_entries, start_timer). The naming is predictable and readable throughout, with no deviations in style or convention.
With 9 tools, this server is well-scoped for time tracking and management. Each tool serves a specific, necessary function in the domain, from core operations like adding entries and managing timers to analytics features like finding overtime users and weekly summaries, without being overly sparse or bloated.
The tool set provides complete coverage for time tracking workflows: creating entries (add_time_entry, start_timer, stop_timer), retrieving entries by various criteria (find_project_time_entries, find_user_time_entries, search_time_entries), and analytics (find_overtime_users, find_undertime_users, get_user_weekly_summary). There are no obvious gaps, enabling agents to handle full CRUD-like operations and reporting.
Maintenance
Related MCP Connectors
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Track time in Clockify: time entries, projects, clients, tags and reports; start, stop and log time.
Time tracking you talk to: log, check and fix your work hours from your AI assistant.
Read your tracked time and projects, pause tracking or add a note, from Claude or ChatGPT.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides comprehensive integration with the Clockify time tracking API, enabling automated time entry management, project organization, task tracking, and reporting through a standardized interface.299 npm6MIT
- AlicenseNot gradedqualityDmaintenanceIntegrates with Clockify time tracking API to retrieve user information, manage projects, and log time entries with flexible time specifications across workspaces.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Clockify time tracking API to manage time entries, projects, tasks, and workspaces through natural language commands.81 npm5ISC
- AlicenseBqualityDmaintenanceEnables time tracking and project management through the Clockify API. Supports starting/stopping timers, logging time entries, managing projects and tasks, and generating reports with natural language commands.2132 npmMIT