Clockify Time Tracking MCP server
✓ VerifiedAllows an AI assistant to query workspaces, projects, and time entries, generate reports, and manage clients, invoices, and expenses through natural language.
Also known as tracegazer/clockify-mcp, clockify-mcp
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 158
- Latest version
- 0.3.2
- Last commit
- Jul 20, 2026
- License
- MIT
What is Clockify Time Tracking MCP?
Clockify Time Tracking allows an AI assistant to query workspaces, projects, and time entries, generate reports, and manage clients, invoices, and expenses through natural language.
Summary generated from the project's README
About Clockify Time Tracking MCP server
Managing time tracking and business administration through natural language is what this server enables for users of Clockify. It allows an AI assistant to interact with your workspace data to query projects, clients, and time entries, or to generate various reports including weekly, summary, and expense reports. Users can connect it to Claude Desktop or other compatible clients using an API key and can choose between three distinct access levels: read-only, time-tracking for logging hours, or full access for managing all aspects of the platform.
Developers can deploy the server locally using pip, uvx, or Docker. When configured with full access mode, the assistant gains the ability to manage complex business workflows such as creating invoices, handling expense categories, managing time-off requests, and organizing scheduling assignments. The server supports different regions and custom base URLs for subdomain workspaces, ensuring it works across various global setups and enterprise environments.
Written from the project's README. Every use case is checked against a quote from it.
How to install Clockify Time Tracking MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Clockify Time Tracking MCP in Claude Code
$ claude mcp add --env 'CLOCKIFY_API_KEY=<YOUR_CLOCKIFY_API_KEY>' clockify-mcp -- uvx clockify-mcpInstall Clockify Time Tracking MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"clockify-mcp": {
"command": "uvx",
"args": [
"clockify-mcp"
],
"env": {
"CLOCKIFY_API_KEY": "<YOUR_CLOCKIFY_API_KEY>"
}
}
}
}Install Clockify Time Tracking MCP in VS Code
.vscode/mcp.json
{
"servers": {
"clockify-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"clockify-mcp"
],
"env": {
"CLOCKIFY_API_KEY": "<YOUR_CLOCKIFY_API_KEY>"
}
}
}
}Install Clockify Time Tracking MCP in VS Code CLI
$ code --add-mcp '{"name":"clockify-mcp","type":"stdio","command":"uvx","args":["clockify-mcp"],"env":{"CLOCKIFY_API_KEY":"<YOUR_CLOCKIFY_API_KEY>"}}'Install Clockify Time Tracking MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"clockify-mcp": {
"command": "uvx",
"args": [
"clockify-mcp"
],
"env": {
"CLOCKIFY_API_KEY": "<YOUR_CLOCKIFY_API_KEY>"
}
}
}
}Install Clockify Time Tracking MCP in Codex
$ codex mcp add clockify-mcp --env 'CLOCKIFY_API_KEY=<YOUR_CLOCKIFY_API_KEY>' --env 'CLOCKIFY_API_KEY=<YOUR_CLOCKIFY_API_KEY>' -- uvx clockify-mcpInstall Clockify Time Tracking MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.clockify-mcp] command = "uvx" args = ["clockify-mcp"] [mcp_servers.clockify-mcp.env] CLOCKIFY_API_KEY = "<YOUR_CLOCKIFY_API_KEY>"
Install Clockify Time Tracking MCP in Gemini CLI
$ gemini mcp add -s user -e 'CLOCKIFY_API_KEY=<YOUR_CLOCKIFY_API_KEY>' -e 'CLOCKIFY_API_KEY=<YOUR_CLOCKIFY_API_KEY>' clockify-mcp uvx -- clockify-mcpInstall Clockify Time Tracking MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"clockify-mcp": {
"command": "uvx",
"args": [
"clockify-mcp"
],
"env": {
"CLOCKIFY_API_KEY": "<YOUR_CLOCKIFY_API_KEY>"
}
}
}
}Configuration
CLOCKIFY_API_KEYRequiredSecretClockify API key (Profile Settings -> API).
CLOCKIFY_API_KEYRequiredSecretClockify API key (Profile Settings -> API).
CLOCKIFY_ACCESS_MODEWrite access mode: read (default, read-only) | time-tracking (time-entry writes only) | full (all writes)
CLOCKIFY_ACCESS_MODEWrite access mode: read (default, read-only) | time-tracking (time-entry writes only) | full (all writes)
CLOCKIFY_DEFAULT_WORKSPACE_IDDefault workspace id used when a tool call omits workspace_id.
CLOCKIFY_DEFAULT_WORKSPACE_IDDefault workspace id used when a tool call omits workspace_id.
CLOCKIFY_TELEMETRYOTEL_EXPORTER_OTLP_ENDPOINTOTEL_EXPORTER_OTLP_HEADERSOTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCEOTEL_SERVICE_NAME
| Name | Description | |
|---|---|---|
| CLOCKIFY_API_KEY | Clockify API key (Profile Settings -> API). | RequiredSecret |
| CLOCKIFY_API_KEY | Clockify API key (Profile Settings -> API). | RequiredSecret |
| CLOCKIFY_ACCESS_MODE | Write access mode: read (default, read-only) | time-tracking (time-entry writes only) | full (all writes) | |
| CLOCKIFY_ACCESS_MODE | Write access mode: read (default, read-only) | time-tracking (time-entry writes only) | full (all writes) | |
| CLOCKIFY_DEFAULT_WORKSPACE_ID | Default workspace id used when a tool call omits workspace_id. | |
| CLOCKIFY_DEFAULT_WORKSPACE_ID | Default workspace id used when a tool call omits workspace_id. | |
| CLOCKIFY_TELEMETRY | — | |
| OTEL_EXPORTER_OTLP_ENDPOINT | — | |
| OTEL_EXPORTER_OTLP_HEADERS | — | |
| OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE | — | |
| OTEL_SERVICE_NAME | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabletracegazer/clockify-mcp is public and reachablegithub.com/tracegazer/clockify-mcp ↗Pass
- Package names this repository as its sourceclockify-mcp names tracegazer/clockify-mcp as sourcepypi.org/project/clockify-mcp/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for clockify-mcppypi.org/project/clockify-mcp/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-20github.com/tracegazer/clockify-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from clockify-mcpPass
- No critical advisory in the package or its dependencies32 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubclockify-mcp
A Model Context Protocol server for the Clockify time-tracking API.
Give your AI assistant access to your Clockify data — query workspaces, projects, and time entries, generate reports, log hours, and manage clients, invoices, and more — all through natural language.
112 tools across 18 domains. Read-only by default, with optional write operations behind explicit opt-in.
Install in one click
The easiest way to use this server with Claude Desktop (and other MCPB-compatible clients) is the prebuilt bundle:
➡️ Download clockify-mcp.mcpb — then double-click it. Claude Desktop opens the installer, prompts for your Clockify API key, and you're done. No Python, no npx/uvx, no config files.
The .mcpb is attached to every GitHub Release and mirrored on Smithery. Prefer a package manager or container? See Quick start below.
What can it do?
48 read-only tools are available today (Phase 0–8b — 18 domains). 64 write tools (create/update/delete across clients, projects, tasks, tags, time entries, holidays, expenses, and expense categories, plus time-off policy/request management, approval submit/resubmit/update, custom-field create/update/delete and project assignment, scheduling assignment management, invoice and payment management, shared-report management, and webhook create/update/delete/token) register when you set CLOCKIFY_ACCESS_MODE=full (or the back-compat CLOCKIFY_ENABLE_WRITES=true). A middle time-tracking mode exposes only the time-entry writes for logging hours — see Access modes.
| Domain | Tools | Tool names |
|---|---|---|
| Workspaces | 3 | get_current_user, list_workspaces, get_workspace |
| Users | 3 | list_users, get_user_member_profile, find_user_team_manager |
| Groups | 1 | list_user_groups |
| Clients | 2 | list_clients, get_client |
| Projects | 2 | list_projects, get_project |
| Tasks | 2 | list_tasks, get_task |
| Tags | 2 | list_tags, get_tag |
| Time entries | 2 | list_time_entries, get_time_entry |
| Reports | 6 | generate_detailed_report, generate_summary_report, generate_weekly_report, generate_attendance_report‡, generate_expense_report‡, export_report (PDF/CSV/XLSX to a file) |
| Shared reports | 2 | list_shared_reports, get_shared_report |
| Time off† | 5 | list_time_off_policies, get_time_off_policy, list_time_off_balances_by_policy, list_time_off_balances_by_user, list_time_off_requests |
| Holidays† | 2 | list_holidays, list_holidays_in_period |
| Expenses† | 4 | list_expenses, get_expense, list_expense_categories, download_expense_receipt |
| Approvals† | 1 | list_approval_requests |
| Custom fields† | 2 | list_workspace_custom_fields, list_project_custom_fields |
| Scheduling† | 3 | list_scheduled_assignments, get_project_scheduling_totals, get_user_scheduling_totals |
| Invoices† | 3 | list_invoices, get_invoice, get_invoice_payments |
| Webhooks† | 3 | list_webhooks, get_webhook, get_webhook_logs |
† Time off, Holidays, Expenses, Approvals, Custom fields, Scheduling, Invoices, and Webhooks are paid Clockify features — these tools error (HTTP 402/403/404) on plans without them.
‡ generate_attendance_report and generate_expense_report (and export_report for those two types) need the workspace's attendance/Expenses add-ons; the time-based reports (detailed/summary/weekly) and shared reports work on the free plan.
Write tools (opt-in — set CLOCKIFY_ACCESS_MODE=full):
| Domain | Tools | Tool names |
|---|---|---|
| Clients | 3 | create_client, update_client, delete_client |
| Projects | 3 | create_project, update_project, delete_project |
| Tasks | 3 | create_task, update_task, delete_task |
| Tags | 3 | create_tag, update_tag, delete_tag |
| Time entries | 7 | create_time_entry, update_time_entry, delete_time_entry, duplicate_time_entry, bulk_update_time_entries, create_time_entry_for_user, stop_running_timer |
| Shared reports | 3 | create_shared_report, update_shared_report, delete_shared_report |
| Time off† | 5 | create_time_off_policy, create_time_off_request, approve_time_off_request, reject_time_off_request, withdraw_time_off_request |
| Holidays† | 3 | create_holiday, update_holiday, delete_holiday |
| Expenses† | 7 | create_expense, update_expense, delete_expense, create_expense_category, update_expense_category, delete_expense_category, archive_expense_category |
| Approvals† | 4 | submit_approval_request, submit_approval_request_for_user, resubmit_approval_entries, update_approval_request |
| Custom fields† | 5 | create_workspace_custom_field, update_workspace_custom_field, delete_workspace_custom_field, set_project_custom_field, remove_project_custom_field |
| Scheduling† | 5 | create_scheduled_assignment, update_scheduled_assignment, delete_scheduled_assignment, publish_scheduled_assignment, copy_scheduled_assignment |
| Invoices† | 9 | create_invoice, update_invoice, change_invoice_status, duplicate_invoice, delete_invoice, create_invoice_item, update_invoice_item, delete_invoice_item, create_invoice_payment |
| Webhooks† | 4 | create_webhook, update_webhook, delete_webhook, generate_webhook_token |
† Time off, Holidays, Expenses, Approvals, Custom fields, Scheduling, Invoices, and Webhooks are paid Clockify features — these tools error (HTTP 402/403/404) on plans without them.
create_expense and update_expense accept an optional local receipt file, uploaded via multipart.
Quick start
1. Install
pip install clockify-mcp
Or run without installing (requires uv):
uvx clockify-mcp
Or use the container image (published to GHCR on every release):
docker run --rm -i -e CLOCKIFY_API_KEY=your-key ghcr.io/tracegazer/clockify-mcp:latest
2. Connect to Claude Desktop
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"clockify": {
"command": "uvx",
"args": ["clockify-mcp"],
"env": {
"CLOCKIFY_API_KEY": "your-api-key"
}
}
}
}
Restart Claude Desktop. Ask: "What workspaces do I have in Clockify?"
{
"mcpServers": {
"clockify": {
"command": "clockify-mcp",
"env": {
"CLOCKIFY_API_KEY": "your-api-key"
}
}
}
}
By default the server is read-only. Opt into writes with CLOCKIFY_ACCESS_MODE:
| Mode | Reads | Writes |
|---|---|---|
read (default) |
everything | nothing |
time-tracking |
everything | time-entry writes only (log & edit hours) |
full |
everything | all write tools (clients, projects, invoices, …) |
{
"mcpServers": {
"clockify": {
"command": "uvx",
"args": ["clockify-mcp"],
"env": {
"CLOCKIFY_API_KEY": "your-api-key",
"CLOCKIFY_ACCESS_MODE": "full"
}
}
}
}
Compatibility: the legacy
CLOCKIFY_ENABLE_WRITES=truestill works and maps tofull. If both are set,CLOCKIFY_ACCESS_MODEwins. Intime-trackingmode,duplicate/bulkalways act on the authenticated user; forupdate/deleteby id the assistant is told to confirm before touching an entry that may belong to someone else.
Warning: write mode lets the connected agent create, modify, and delete real data through your Clockify credential.
delete_*tools andwithdraw_time_off_requestare irreversible.
3. Get your API key
Log into Clockify → Profile Settings → API → copy your API key.
Configuration
Configuration resolves in this order (highest priority first):
- Environment variables (always win)
- TOML config at
~/.config/clockify-mcp/config.toml
| Env var | TOML key | Description |
|---|---|---|
CLOCKIFY_API_KEY |
api_key |
Your Clockify API key (required) |
CLOCKIFY_REGION |
region |
global (default) | euc1 (EU) | use2 (USA) | euw2 (UK) | apse2 (AU) |
CLOCKIFY_BASE_URL |
base_url |
Override for subdomain workspaces, e.g. https://acme.clockify.me |
CLOCKIFY_DEFAULT_WORKSPACE_ID |
default_workspace_id |
Fallback workspace when a tool call omits workspace_id |
CLOCKIFY_ACCESS_MODE |
access_mode |
read (default) | time-tracking (read + log hours) | full (all writes) |
CLOCKIFY_ENABLE_WRITES |
enable_writes |
Back-compat alias: true = access_mode=full. CLOCKIFY_ACCESS_MODE takes precedence. |
CLOCKIFY_TELEMETRY |
telemetry_enabled |
Enable OpenTelemetry — default false |
CLOCKIFY_TELEMETRY_DETAIL |
telemetry_detail |
Span detail: metadata (default), ids, or full |
Access modes: read exposes only read tools. time-tracking adds the time-entry write tools (create/update/delete/duplicate/bulk) for logging hours and nothing else — duplicate/bulk always act on the authenticated user, and for update/delete by id the assistant is told to confirm before touching an entry that may belong to someone else. full exposes all write tools. This gates which MCP tools the server registers; it is not a replacement for the API key's own permissions.
See config.toml.example for a copy-paste template.
# ~/.config/clockify-mcp/config.toml
api_key = "your-clockify-api-key"
# region = "global"
# default_workspace_id = ""
# access_mode = "read" # read | time-tracking | full
Tip: create the config directory first:
mkdir -p ~/.config/clockify-mcp
Running the server
clockify-mcp # STDIO transport (default)
clockify-mcp --transport sse # SSE/HTTP transport
Security note: STDIO (the default) keeps everything local. The
sseandstreamable-httptransports have no built-in authentication — only use them bound to loopback or behind an authenticated reverse proxy.
Notes
- Workspace scope: Almost every Clockify operation is scoped to a workspace (
/workspaces/{workspaceId}/...). Tools accept an optionalworkspace_id; when omitted they fall back toCLOCKIFY_DEFAULT_WORKSPACE_ID. If neither is set, the tool asks you to resolve one first vialist_workspaces. - Pagination: list tools take optional
page/page_sizeand return one page. The high-volume lists (list_time_entries,list_projects,list_clients,list_tasks,list_tags,list_users) also acceptfetch_all=trueto follow pagination and return every page concatenated (may make several API calls). - Errors: failures carry a category —
PLAN_REQUIRED,ACCESS_DENIED, orAUTH— so the assistant knows whether to ask you to upgrade the plan, enable a module, or fix the key. See Paid features.
Paid features & enabling them in Clockify
Many domains are gated by two independent things — both must be true for the tools to work:
1. The workspace plan must include the feature. Otherwise the API returns 402 (or a "subscription" message) and the server raises ClockifyAPIError with category PLAN_REQUIRED.
| Feature | Minimum plan |
|---|---|
| Reports (detailed/summary/weekly), Shared reports | Free |
| Webhooks | Free (up to 3) — paid for more |
| Time off, Holidays, Invoices, Approvals | Standard |
| Expenses (incl. expense report), Custom fields, Scheduling | Pro |
| Attendance report | Pro (attendance/time-tracking add-on) |
2. The module must be enabled in the workspace. Even on the right plan, an admin must turn these on in Clockify → Workspace Settings: Time off, Expenses, Approval, Invoicing, Scheduling. Until enabled, the API returns 403 "Access Denied" and the server raises ClockifyAPIError with category ACCESS_DENIED. (Custom fields, webhooks, and reports need no separate toggle.)
When an operation fails, the error category says what to do:
PLAN_REQUIRED— upgrade the workspace plan (Standard/Pro).ACCESS_DENIED— enable the feature in Workspace Settings, or check the API key user's role/permission.AUTH— the API key is missing, invalid, or revoked.
Observability (optional)
The server can emit OpenTelemetry traces, metrics, and logs — completely opt-in and vendor-neutral. Export to any OTLP-compatible backend (Dynatrace, Grafana, Datadog, Jaeger, etc.). When disabled, opentelemetry is never imported.
pip install "clockify-mcp[telemetry]"
export CLOCKIFY_TELEMETRY=1
OTLP endpoint and headers are configured via standard OpenTelemetry env vars (not in the TOML file). CLOCKIFY_TELEMETRY_DETAIL controls how much argument/payload data is attached (metadata default → ids → full); the API key is always redacted.
export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-env>.live.dynatrace.com/api/v2/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token <YOUR_DT_TOKEN>"
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
export OTEL_SERVICE_NAME=clockify-mcp
Token scopes needed: openTelemetryTrace.ingest, metrics.ingest, logs.ingest. Dynatrace's OTLP metrics ingest requires delta temporality — without that env var, metric export fails with 400 Bad Request.
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_SERVICE_NAME=clockify-mcp
Signals emitted:
- Traces — a span per MCP tool call (
execute_tool <name>) and per Clockify API request - Metrics —
mcp.tool.duration,mcp.tool.errors, and Clockify client request durations - Logs — tool errors and unexpected API response shapes, correlated to traces (OTLP only, never stdout)
Development
git clone https://github.com/tracegazer/clockify-mcp
cd clockify-mcp
uv sync --extra dev
CLOCKIFY_API_KEY=dummy uv run clockify-mcp --help
uv run pytest -q
uv run ruff check src/ tests/
License
Clockify Time Tracking MCP questions
How do I add Clockify Time Tracking MCP to Claude Code?
Run claude mcp add --env 'CLOCKIFY_API_KEY=<YOUR_CLOCKIFY_API_KEY>' clockify-mcp -- uvx clockify-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Clockify Time Tracking MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Is the server read-only by default?
Yes, the server is read-only by default. You must explicitly opt-in to write operations using the CLOCKIFY_ACCESS_MODE configuration.
How do I get my Clockify API key?
Log into your Clockify account, go to Profile Settings, select API, and copy your key.