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

$3

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

$3

1. Install dependencies:
``bash
npm install
`

2. Build the project:
`bash
npm run build
`

3. Environment Configuration:

Create a .env file:
`env
# 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

$3

`bash
npm run dev
`
Server runs with auto-restart on file changes at http://localhost:3000.

$3

`bash
npm start
`

$3

`bash
npm test
`

$3

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

`bash

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

$3

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

$3

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

`yaml
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

$3

#### Via Smithery (Recommended)
`bash
npx -y @smithery/cli install clockify-mcp-server --client claude
`

#### Manual Installation

1. Install TypeScript globally:
`bash
npm i -g ts-node
`

2. Add to your Claude Desktop configuration (claude_desktop_config.json):
`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"
}
}
}
}
`

$3

The server integrates seamlessly with the MCP Dashboard backend:

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

🛠️ Available Tools

$3

#### 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"
`

$3

#### 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"
`

$3

#### 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"
`

$3

#### find_workspaces
List all accessible workspaces for the authenticated user.

Example Usage:
`
"What workspaces do I have access to?"
`

$3

#### 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"
`

$3

#### 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

$3

`typescript
// 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

$3

`http
GET /health
`

Response:
`json
{
"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
}
`

$3

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:

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

🚀 Deployment

$3

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

$3

| 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 |

$3

The server includes Elastic Beanstalk deployment configuration:

`bash

Deploy to AWS Elastic Beanstalk

eb init
eb create clockify-mcp-server
eb deploy
`

🧪 Testing

$3

`bash
npm test
`

$3

Tests cover:
- Tool functionality
- API client operations
- Authentication flow
- Error handling scenarios
- Input validation

$3

Test individual tools using the MCP protocol:

`json
{
"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

$3

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
`

$3

`javascript
// 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

$3

- 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



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

$3

First, install ts-node globally

npm i -g ts-node

Then insert the MCP server in claude_desktop_config

`json
{
"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.