# Clockify MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with the Clockify time tracking API.

## Installation

```bash
npm install -g @yikizi/clockify-mcp
```

Or use directly with npx:
```bash
npx @yikizi/clockify-mcp
```

## Features

- **Workspace Management**: List workspaces, get current user, list workspace users
- **Project Management**: List/create projects, list/create tasks
- **Time Tracking**: Start/stop timers, log time entries, update/delete entries
- **Reporting**: Generate summary and detailed reports with grouping and filtering
- **Tags & Clients**: List and create tags, list clients

## Setup

### 1. Get your Clockify API Key

1. Go to [Clockify User Settings](https://app.clockify.me/user/preferences#advanced)
2. Scroll to "API" section
3. Click "Generate" to create an API key

### 2. Configure Claude Code

Add to your Claude Code MCP settings (`~/.claude.json` or via Claude Code settings):

**Option A: CLI argument (recommended)**
```json
{
  "mcpServers": {
    "clockify": {
      "command": "npx",
      "args": ["@yikizi/clockify-mcp", "--api-key", "your-api-key-here"]
    }
  }
}
```

**Option B: Environment variable**
```json
{
  "mcpServers": {
    "clockify": {
      "command": "npx",
      "args": ["@yikizi/clockify-mcp"],
      "env": {
        "CLOCKIFY_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

**Option C: .env file**

Create a `.env` file in your working directory:
```
CLOCKIFY_API_KEY=your-api-key-here
```

## Available Tools

### Convenience Tools (Recommended)
These auto-detect your user and workspace:

- `start_timer` - Start a timer (just provide description and optional project)
- `stop_current_timer` - Stop whatever timer is running
- `get_running_timer` - Check if a timer is running and see elapsed time
- `log_time` - Log completed time with human-readable duration ("1h30m", "2h", "45m")

### Workspace Tools
- `get_workspaces` - List all workspaces
- `get_current_user` - Get authenticated user info
- `get_workspace_users` - List users in a workspace

### Project Tools
- `get_projects` - List projects (with archive filter)
- `create_project` - Create a new project
- `get_project_tasks` - List tasks in a project
- `create_task` - Create a task

### Time Entry Tools (Low-level)
- `get_time_entries` - Get time entries for a user (with date/project filters)
- `create_time_entry` - Create a time entry (use `start_timer` or `log_time` instead)
- `stop_timer` - Stop timer for specific user (use `stop_current_timer` instead)
- `update_time_entry` - Update an existing entry
- `delete_time_entry` - Delete a time entry

### Reporting Tools
- `get_summary_report` - Aggregated report grouped by project/user/client
- `get_detailed_report` - Detailed list of time entries with filters

### Tag & Client Tools
- `get_tags` - List all tags
- `create_tag` - Create a new tag
- `get_clients` - List all clients

## Usage Examples

Once configured, you can ask Claude things like:

- "Start a timer for working on the API project"
- "Stop my timer"
- "Log 2 hours for documentation work"
- "Is my timer running?"
- "Generate a summary report for last week"
- "How much time did I log this month?"
- "List all my projects"

## Changelog

### v1.2.2
- **Config**: API key can now be passed via `--api-key` CLI argument
- **Config**: API key can be read from `.env` file in current directory
- **Improvement**: Better error message showing all config options

### v1.2.1
- **Bugfix**: `get_running_timer` now properly finds running timers (was only checking 1 entry)
- **Bugfix**: `stop_current_timer` now correctly stops timers
- **Improvement**: `stop_current_timer` accepts optional `end` time for backdating

### v1.2.0
- Human-readable durations in responses (`1h 30m` instead of `PT1H30M`)
- Relative period filters for `get_time_entries`: `today`, `yesterday`, `this_week`, `last_week`, `this_month`, `last_month`
- `get_time_entries` now defaults to current user/workspace (no IDs needed!)
- Responses include total time across all entries

### v1.1.0
- Added convenience tools: `start_timer`, `stop_current_timer`, `get_running_timer`, `log_time`
- Auto-detect user and workspace (no need to call `get_current_user` first)
- Human-readable duration format ("1h30m") for `log_time`
- Input validation to catch date typos early
- Warns if timer is already running when starting a new one

### v1.0.0
- Initial release with core Clockify API support

## License

MIT