# Clockify MCP Server
A modular Model Context Protocol (MCP) server for integrating with the Clockify time tracking API.
## Installation
### From npm (Recommended)
```bash
npm install -g clockify-mcp-server
```
### From Source
```bash
git clone https://github.com/yourusername/clockify-mcp-server.git
cd clockify-mcp-server
npm install
```
## Features
This MCP server provides three tools:
1. **iam** - Get current user information from Clockify API
2. **getAllProjects** - Get all projects for a specific workspace
3. **logTimeEntry** - Log time entries with flexible time specifications
## Architecture
The server is built with a modular architecture:
- `src/server.js` - Main server class with `registerTool` interface
- `src/api.js` - Shared API utilities for Clockify requests
- `src/tools/` - Individual tool modules with Zod schema validation
- `index.js` - Entry point that registers all tools
## Setup
### 1. Set Environment Variables
Create a `.env` file or set the environment variable with your Clockify API key:
```bash
export CLOCKIFY_API_KEY=your_api_key_here
```
You can get your API key from [Clockify Settings > API](https://clockify.me/user/settings#api).
### 2. Run the Server
If installed globally:
```bash
clockify-mcp-server
```
If running from source:
```bash
npm start
```
Or for development with auto-restart:
```bash
npm run dev
```
## Usage in MCP Clients
After installing, you can configure your MCP client to use this server. For example, in Claude Desktop:
```json
{
"mcpServers": {
"clockify": {
"command": "clockify-mcp-server",
"env": {
"CLOCKIFY_API_KEY": "your_api_key_here"
}
}
}
}
```
## Tools
### iam
Get current user information from Clockify API.
**Parameters:** None
**Example:**
```json
{
"name": "iam"
}
```
### getAllProjects
Get all projects for a specific workspace.
**Parameters:**
- `workspaceId` (string, required): The workspace ID to get projects for
**Example:**
```json
{
"name": "getAllProjects",
"arguments": {
"workspaceId": "60c1beaf8747147d9ac70b4b"
}
}
```
### logTimeEntry
Log a time entry in Clockify.
**Parameters:**
- `date` (string, required): Date for the time entry in YYYY-MM-DD format
- `description` (string, required): Description of the work performed
- `projectId` (string, required): ID of the project to log time against
- `workspaceId` (string, required): ID of the workspace
- `startTime` (string, optional): Start time in HH:MM format (defaults to "09:00")
- `endTime` (string, optional): End time in HH:MM format (defaults to "17:00")
**Example:**
```json
{
"name": "logTimeEntry",
"arguments": {
"date": "2024-01-15",
"description": "Working on project documentation",
"projectId": "662f81c0b682f06d79bff487",
"workspaceId": "60c1beaf8747147d9ac70b4b",
"startTime": "09:30",
"endTime": "12:30"
}
}
```
## Getting Workspace and Project IDs
1. Use the `iam` tool to get your user information and available workspaces
2. Use the `getAllProjects` tool with a workspace ID to get project IDs
3. Use these IDs in the `logTimeEntry` tool
## Error Handling
The server includes comprehensive error handling for:
- Missing or invalid API keys
- Invalid date/time formats
- Missing required parameters
- API request failures
- Time validation (end time must be after start time)
All errors are returned with descriptive messages to help troubleshoot issues.
## Development
### Adding New Tools
The server uses a clean `registerTool` interface. To add a new tool:
1. Create a new file in `src/tools/` with your tool definition:
```javascript
import { z } from "zod";
import { makeApiRequest } from "../api.js";
export const myNewTool = {
name: "myNewTool",
config: {
title: "My New Tool",
description: "Description of what the tool does",
inputSchema: z.object({
param1: z.string().describe("Description of param1"),
param2: z.number().optional().describe("Optional param2")
})
},
handler: async ({ param1, param2 }) => {
// Your tool logic here
const result = await makeApiRequest("/some-endpoint");
return {
content: [{
type: "text",
text: JSON.stringify(result, null, 2)
}]
};
}
};
```
2. Export it from `src/tools/index.js`
3. Register it in `index.js`:
```javascript
server.registerTool(
myNewTool.name,
myNewTool.config,
myNewTool.handler
);
```
The server automatically handles:
- Zod schema validation
- JSON schema conversion for MCP
- Error handling and formatting
- Tool registration and discovery
## Publishing
To publish updates to npm:
1. Update the version in `package.json`
2. Run `npm publish`
## License
MIT
## Requirements
- Node.js 18.0.0 or higher
- Clockify API key
