clockify

This Clockify MCP Server lets you manage Clockify time entries by conversing with an AI tool. It exposes an MCP endpoint that translates natural language prompts into Clockify API actions such as creating, updating, or listing time entries. By running locally with tsx, the server loads your MCP logic from the provided source and communicates with Clockify using the API token you supply. When used with AI tools, you can prompt the system to log work, adjust durations, or annotate entries, and the server will perform the corresponding Clockify API calls behind the scenes.

To use it, supply your Clockify API URL and token as environment variables in your MCP config. The server then authenticates requests and performs operations like starting a timer, creating a time entry for a project, or listing entries for today. If your AI assistant or client supports structured prompts or intents, you can craft prompts such as “log 2 hours for Client A on Project X today” or “show my Clockify entries for this week,” and the MCP server will execute the appropriate Clockify actions via the API.

Prerequisites:

• Node.js and npm installed on your machine
• tsx installed globally (see steps below) or use a container/CLI installer if you prefer

Option A: Install via Smithery (recommended for Claude Desktop)

1. Install using Smithery CLI:

npx -y @smithery/cli install @https-eduardo/clockify-mcp-server --client claude

2. Launch the server as directed by Smithery and point Claude Desktop to the provided MCP endpoint.

Option B: Manual installation

1. Install tsx globally (for running TypeScript entry points):

npm i -g tsx

2. Create your MCP config file (see mcp_config example in this repo) and start the server using tsx:

tsx ABSOLUTE_PATH/src/index.ts --local

3. Ensure CLOCKIFY_API_URL and CLOCKIFY_API_TOKEN are set in your environment or in the config as shown below.

Note: If you are deploying elsewhere, adapt the command to your environment (e.g., using a PM2 process manager or a container) while keeping the same entry point and environment variables.

Environment variables:

• CLOCKIFY_API_URL should point to the Clockify API base URL (default shown is https://api.clockify.me/api/v1)
• CLOCKIFY_API_TOKEN must be a valid Clockify API token with permissions to create and manage time entries

Common issues:

• Invalid API token or insufficient permissions: double-check token scopes in Clockify
• Network/firewall blocks to api.clockify.me: ensure outbound HTTPS access is allowed
• tsx not found after install: ensure tsx is installed globally and accessible in PATH

Configuration tips:

• Keep the API URL and token in environment variables to avoid committing secrets
• If you deploy in a serverless or container environment, pass env vars through your deployment tool
• When testing locally, you can use the --local flag as shown in the config example