clockify-mcp-server 0.1.0

MCP server for Clockify time tracking API

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

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-server

Manual 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-server

Configuration

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 days

2. 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 month

3. search_time_entries

Search time entries by description phrase.

Parameters:

• search_phrase (required): Phrase to search for in descriptions
• user_name (optional): Limit search to specific user
• 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

Example:

Find all time entries containing "meeting" in the description

4. add_time_entry

Add a time entry for a specific user.

Parameters:

• user_name (required): Name of the user
• description (required): Description of the work
• start_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 with
• task_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 meetings

5. start_timer

Start a timer for the current user.

Parameters:

• description (required): What you're working on
• project_name (optional): Project to associate with
• task_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" project

6. stop_timer

Stop the currently running timer.

Parameters:

• workspace_id (optional): Workspace ID

Example:

Stop my current timer

7. 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 month

8. 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 user
• weeks (optional): Number of weeks to analyze (default: 4)
• workspace_id (optional): Workspace ID

Example:

Show me John's weekly hours for the past month

Usage 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 License

API 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:

1. Check your internet connection
2. Verify your API key is correct
3. Ensure you're not behind a proxy that blocks API requests

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. 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