Clockify MCP Server

A Model Context Protocol (MCP) server implementation for Clockify time tracking integration. This server enables AI assistants to interact with Clockify's time tracking features through natural language commands.

🚀 Features

• Time Entry Management: Create, list, and manage time entries
• Project Integration: Access and manage Clockify projects
• User Management: Retrieve user information and groups
• Workspace Support: Multi-workspace functionality
• Task Tracking: Integrate with project tasks
• Reports: Generate detailed time tracking reports
• Stateless Architecture: Pure stateless design with AsyncLocalStorage
• Authentication: Bearer token authentication support
• Debug Logging: Conditional debug logging for local development

🛠️ Tech Stack

• Runtime: Node.js (v20+)
• Language: TypeScript
• Framework: Express.js with MCP SDK
• API Client: Axios for Clockify API integration
• Validation: Zod schemas
• Testing: Node.js built-in test runner

📦 Installation

Prerequisites

• Node.js v20.0.0 or higher
• npm v10.0.0 or higher
• Clockify account with API access

Setup

1. Install dependencies:

   npm install

2. Build the project:

   npm run build

3. Environment Configuration:

   Create a .env file:

   # Clockify API Configuration
   CLOCKIFY_API_URL=https://api.clockify.me/api/v1
   CLOCKIFY_API_TOKEN=your_clockify_api_token_here
      
   # Server Configuration  
   PORT=3000
   NODE_ENV=development
   IS_LOCAL=true
   TZ=UTC

🏃‍♂️ Running the Server

Development Mode

npm run dev

Server runs with auto-restart on file changes at http://localhost:3000.

Production Mode

npm start

Testing

npm test

Debug Logging

Debug logging is automatically enabled in development mode and disabled in production. For manual control:

# Enable debug logging
NODE_ENV=development npm start
# OR
DEBUG_MODE=true npm start

# Disable debug logging (production)
NODE_ENV=production npm start

Debug logs are written to:

• Console with [CLOCKIFY-MCP-DEBUG] prefix and timestamps
• No file storage (npm package friendly)

See DEBUG_SETUP.md for detailed configuration.

🔧 Configuration

Clockify API Token

To get your Clockify API token:

1. Log in to your Clockify account
2. Go to Profile Settings → API
3. Generate a new API key
4. Copy the token to your .env file

Smithery Configuration

For use with AI assistants like Claude Desktop, create a smithery.yaml configuration:

startCommand:
  type: stdio
  configSchema:
    type: object
    required:
      - clockifyApiToken
    properties:
      clockifyApiUrl:
        type: string
        default: https://api.clockify.me/api/v1
        description: Base URL for Clockify API
      clockifyApiToken:
        type: string
        default: YOUR_CLOCKIFY_API_TOKEN_HERE
        description: Clockify API token for authentication
  commandFunction: |
    (config) => ({
      command: 'node',
      args: ['build/src/index.js'],
      env: {
        CLOCKIFY_API_URL: config.clockifyApiUrl,
        CLOCKIFY_API_TOKEN: config.clockifyApiToken
      }
    })

🔌 Integration with AI Assistants

Claude Desktop

Via Smithery (Recommended)

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

Manual Installation

1. Install TypeScript globally:

   npm i -g ts-node

2. Add to your Claude Desktop configuration (claude_desktop_config.json):

   {
     "mcpServers": {
       "clockify": {
         "command": "node",
         "args": ["/absolute/path/to/clockify-mcp-server/build/src/index.js"],
         "env": {
           "CLOCKIFY_API_TOKEN": "your_clockify_api_token_here"
         }
       }
     }
   }

MCP Dashboard Integration

The server integrates seamlessly with the MCP Dashboard backend:

// Backend configuration
const mcpServers = {
  clockify: {
    url: 'http://localhost:3000',
    name: 'Clockify Time Tracking'
  }
};

🛠️ Available Tools

Time Entries

create_entry

Create a new time entry in Clockify.

Parameters:

• workspaceId (string, required): Workspace ID
• description (string, required): Time entry description
• start (date, required): Start time
• end (date, required): End time
• projectId (string, optional): Project ID
• billable (boolean, optional): Whether entry is billable (default: true)

Example Usage:

"Create a time entry for 'Website development' from 9 AM to 5 PM today in project XYZ"

list_entries

List time entries for a user within a date range.

Parameters:

• workspaceId (string, required): Workspace ID
• userId (string, required): User ID
• start (date, required): Start date for search
• end (date, required): End date for search

Example Usage:

"Show me my time entries for this week"

Projects

find_project

Search for projects in a workspace.

Parameters:

• workspaceId (string, required): Workspace ID
• name (string, optional): Project name filter

Example Usage:

"Find all projects containing 'website' in the name"

Users & Groups

get_current_user

Get information about the current authenticated user.

Example Usage:

"What's my user information?"

get_all_users

Get all users in a workspace.

Parameters:

• workspaceId (string, required): Workspace ID

Example Usage:

"Show me all users in the workspace"

get_all_groups

Get all user groups in a workspace.

Parameters:

• workspaceId (string, required): Workspace ID

Example Usage:

"List all user groups"

Workspaces

find_workspaces

List all accessible workspaces for the authenticated user.

Example Usage:

"What workspaces do I have access to?"

Tasks

find_tasks

Find tasks within a project.

Parameters:

• workspaceId (string, required): Workspace ID
• projectId (string, required): Project ID

Example Usage:

"Show me all tasks in the current project"

Reports

get_detailed_report

Generate detailed time tracking reports.

Parameters:

• workspaceId (string, required): Workspace ID
• dateRangeStart (date, required): Report start date
• dateRangeEnd (date, required): Report end date
• users (array, optional): User IDs to include
• projects (array, optional): Project IDs to include

Example Usage:

"Generate a detailed report for last month"

🏗️ Project Structure

src/
├── index.ts                 # Main server entry point
├── config/
│   └── api.ts              # API configuration and client setup
├── tools/                   # MCP tool implementations
│   ├── entries.ts          # Time entry management tools
│   ├── projects.ts         # Project management tools
│   ├── users.ts            # User management tools
│   ├── workspaces.ts       # Workspace tools
│   ├── tasks.ts            # Task management tools
│   └── reports.ts          # Reporting tools
├── clockify-sdk/           # Clockify API SDK
│   ├── entries.ts          # Time entries API client
│   ├── projects.ts         # Projects API client
│   ├── users.ts            # Users API client
│   ├── workspaces.ts       # Workspaces API client
│   ├── tasks.ts            # Tasks API client
│   └── reports.ts          # Reports API client
├── validation/             # Zod validation schemas
│   ├── entries/            # Entry validation schemas
│   ├── projects/           # Project validation schemas
│   └── reports/            # Report validation schemas
└── types/
    └── index.ts            # TypeScript type definitions

🔒 Authentication

The server uses stateless bearer token authentication:

1. Token Extraction: Extracts bearer tokens from Authorization headers
2. Validation: Validates tokens against Clockify API
3. Context Isolation: Uses AsyncLocalStorage for request isolation
4. Security: No session storage, completely stateless

Authentication Flow

// Request with Bearer token
Authorization: Bearer your_clockify_api_token

// Server validates token with Clockify API
fetch('https://api.clockify.me/api/v1/workspaces', {
  headers: { 'X-Api-Key': token }
});

// If valid, request proceeds with token context

📊 Monitoring & Health Checks

Health Endpoint

GET /health

Response:

{
  "status": "healthy",
  "service": "Clockify MCP Server",
  "version": "1.0.0",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "clockify_api_url": "https://api.clockify.me/api/v1",
  "stateless": true
}

Error Handling

The server provides comprehensive error handling:

• Authentication Errors: Invalid or missing API tokens
• API Errors: Clockify API communication issues
• Validation Errors: Invalid request parameters
• Network Errors: Connection timeouts and failures

Error responses follow MCP protocol standards:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Authentication required: Valid Bearer token required"
  },
  "id": null
}

🚀 Deployment

Docker Deployment

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | CLOCKIFY_API_URL | No | https://api.clockify.me/api/v1 | Clockify API base URL | | CLOCKIFY_API_TOKEN | Yes | - | Clockify API token | | PORT | No | 3000 | Server port | | NODE_ENV | No | development | Environment mode | | IS_LOCAL | No | false | Local development flag | | TZ | No | UTC | Timezone setting |

Elastic Beanstalk

The server includes Elastic Beanstalk deployment configuration:

# Deploy to AWS Elastic Beanstalk
eb init
eb create clockify-mcp-server
eb deploy

🧪 Testing

Running Tests

npm test

Test Coverage

Tests cover:

• Tool functionality
• API client operations
• Authentication flow
• Error handling scenarios
• Input validation

Manual Testing

Test individual tools using the MCP protocol:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_entries",
    "arguments": {
      "workspaceId": "workspace-id",
      "userId": "user-id",
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    }
  }
}

💡 Usage Examples

Natural Language Commands

The MCP server enables natural language interaction:

User: "Start tracking time for website development"
AI: Creates time entry with current timestamp

User: "How much time did I spend on project X last week?"
AI: Generates report for specified project and date range

User: "Stop my current timer and log 8 hours for database work"
AI: Updates time entry with specified duration and description

Integration with Workflows

// Automated time tracking workflow
const workflow = {
  morning: () => ai.chat("Start tracking time for daily standup"),
  coding: () => ai.chat("Switch time tracking to development work"),
  evening: () => ai.chat("Stop timer and show today's summary")
};

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Add tests for new functionality
• Update documentation for new tools
• Maintain stateless architecture
• Use Zod for input validation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Clockify API for the comprehensive time tracking API
• Model Context Protocol for the integration standard
• TypeScript for type safety
• Zod for schema validation

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

Installing Manually

First, install ts-node globally

npm i -g ts-node

Then insert the MCP server in claude_desktop_config

{
  "mcpServers": {
    "clockify-time-entries": {
      "command": "ts-node",
      "args": ["ABSOLUTE_PATH/src/index.ts"],
      "env": {
        "CLOCKIFY_API_URL": "https://api.clockify.me/api/v1",
        "CLOCKIFY_API_TOKEN": "YOUR_CLOCKIFY_API_TOKEN_HERE"
      }
    }
  }
}

You can also compile the Typescript code using tsc and then change the config to use default node command and point to the js file.