# Clockify Timer MCP Server

Minimal MCP server for managing Clockify timers. Start/stop timers, check what's running, and view recent entries — all through Claude.

## Tools

| Tool | Description |
|------|-------------|
| `get-workspaces` | List your Clockify workspaces |
| `get-projects` | List projects in a workspace |
| `start-timer` | Start a timer (auto-stops any running timer first) |
| `stop-timer` | Stop the current timer |
| `current-timer` | Check what's currently running |
| `recent-entries` | List recent time entries |

## Setup

### 1. Get your Clockify API token

Go to [Clockify Profile Settings](https://app.clockify.me/user/preferences#advanced) → scroll to "API" → generate or copy your API key.

### 2. Configure Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "clockify": {
      "command": "npx",
      "args": ["tsx", "/ABSOLUTE/PATH/TO/clockify-mcp/src/index.ts"],
      "env": {
        "CLOCKIFY_API_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

### 3. Use it

- "Start a timer for API refactoring work"
- "What timer is running right now?"
- "Stop the timer"
- "Show my last 5 time entries"
- "Start tracking meeting prep, billable, on the Acme project"

## Security notes

- **No shared mutable state** — client config is immutable, no global singletons
- **All Clockify IDs validated** against 24-char hex pattern before URL interpolation (prevents path traversal)
- **No axios** — uses native `fetch`, zero HTTP dependency vulnerabilities
- **Error sanitization** — API errors are truncated and never leak auth headers
- **Fail-fast** — exits immediately if API token is missing
- **0 npm audit vulnerabilities** at time of creation