# 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
