SIGN UPLOG IN
X (Twitter)LinkedInGitHubDiscordYouTube

How to integrate Clockify MCP with LangChain

Connect LangChain to Clockify MCP. List all your active workspaces, add a new client to marketing workspace, and more using natural language, with authentication handled for you.

Get started for freeGet a demo
Clockify logoClockify
Api KeyOauth2

Clockify is a free time tracking software for individuals and teams to monitor work hours across projects. Track, manage, and report time for better productivity and transparency.

74 Tools

Introduction

This guide walks you through connecting Clockify to LangChain using the Composio tool router. By the end, you'll have a working Clockify agent that can log time entries, manage projects and tasks, generate detailed and weekly reports, organize clients and tags, and stop running timers through natural language commands.

This guide will help you understand how to give your LangChain agent real control over a Clockify account through Composio's Clockify MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

Also integrate Clockify with

Claude CodeClaude CoworkOpenAI Agents SDKClaude Agent SDKCodexOpenClawHermesAtomic AgentGoogle ADKVercel AI SDKMastra AILlamaIndexCrewAIPydantic AIAutoGen

TL;DR

Here's what you'll learn:
  • Get and set up your OpenAI and Composio API keys
  • Connect your Clockify project to Composio
  • Create a Tool Router MCP session for Clockify
  • Initialize an MCP client and retrieve Clockify tools
  • Build a LangChain agent that can interact with Clockify
  • Set up an interactive chat interface for testing

What is LangChain?

LangChain is a framework for developing applications powered by language models. It provides tools and abstractions for building agents that can reason, use tools, and maintain conversation context.

Key features include:

  • Agent Framework: Build agents that can use tools and make decisions
  • MCP Integration: Connect to external services through Model Context Protocol adapters
  • Memory Management: Maintain conversation history across interactions
  • Multi-Provider Support: Works with OpenAI, Anthropic, and other LLM providers

What is the Clockify MCP server, and what's possible with it?

The Clockify MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Clockify account. It provides structured and secure access to your team's time tracking data, so your agent can perform actions like managing clients, handling workspace users, setting up webhooks, and retrieving workspace details on your behalf.

  • Workspace user management: Let your agent list all users in a workspace, filter users by advanced criteria, or find team managers for more efficient team organization.
  • Client creation and deletion: Easily create new clients or remove existing ones from your workspace, streamlining project onboarding and cleanup.
  • Webhook automation: Enable your agent to create, delete, and manage webhooks for real-time notifications and integrations with other tools.
  • Workspace overview and navigation: Retrieve a list of all workspaces you belong to, empowering your agent to access and organize time tracking across multiple teams or projects.
  • Addon and webhook token management: Generate new webhook tokens and list all addon webhooks, ensuring secure and automated integrations with third-party services.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step10 STEPS
1

Prerequisites

Before starting this tutorial, make sure you have:
  • Python 3.10 or higher installed on your system
  • A Composio account with an API key
  • An OpenAI API key
  • Basic familiarity with Python and async programming
2

Getting API Keys for OpenAI and Composio

OpenAI API Key
  • Go to the OpenAI dashboard and create an API key. You'll need credits to use the models, or you can connect to another model provider.
  • Keep the API key safe.
Composio API Key
  • Log in to the Composio dashboard.
  • Navigate to your API settings and generate a new API key.
  • Store this key securely as you'll need it for authentication.
3

Install dependencies

npm install @composio/langchain @langchain/core @langchain/openai @langchain/mcp-adapters dotenv

Install the required packages for LangChain with MCP support.

What's happening:

  • @composio/langchain provides Composio integration for LangChain
  • @langchain/mcp-adapters enables MCP client connections
  • @langchain/core is the core agent framework
  • dotenv/config loads environment variables
4

Set up environment variables

bash
COMPOSIO_API_KEY=your_composio_api_key_here
COMPOSIO_USER_ID=your_composio_user_id_here
OPENAI_API_KEY=your_openai_api_key_here

Create a .env file in your project root.

What's happening:

  • COMPOSIO_API_KEY authenticates your requests to Composio's API
  • COMPOSIO_USER_ID identifies the user for session management
  • OPENAI_API_KEY enables access to OpenAI's language models
5

Import dependencies

import { Composio } from '@composio/core';
import { LangchainProvider } from '@composio/langchain';
import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { createAgent } from "langchain";
import * as readline from 'readline';
import 'dotenv/config';

dotenv.config();
What's happening:
  • We're importing LangChain's MCP adapter and Composio SDK
  • The dotenv/config import loads environment variables from your .env file
  • This setup prepares the foundation for connecting LangChain with Clockify functionality through MCP
6

Initialize Composio client

const composioApiKey = process.env.COMPOSIO_API_KEY;
const userId = process.env.COMPOSIO_USER_ID;

if (!composioApiKey) throw new Error('COMPOSIO_API_KEY is not set');
if (!userId) throw new Error('COMPOSIO_USER_ID is not set');

async function main() {
    const composio = new Composio({
        apiKey: composioApiKey as string,
        provider: new LangchainProvider()
    });
What's happening:
  • We're loading the COMPOSIO_API_KEY from environment variables and validating it exists
  • Creating a Composio instance that will manage our connection to Clockify tools
  • Validating that COMPOSIO_USER_ID is also set before proceeding
7

Create a Tool Router session

const session = await composio.create(
    userId as string,
    {
        toolkits: ['clockify']
    }
);

const url = session.mcp.url;
What's happening:
  • We're creating a Tool Router session that gives your agent access to Clockify tools
  • The create method takes the user ID and specifies which toolkits should be available
  • The returned session.mcp.url is the MCP server URL that your agent will use
  • This approach allows the agent to dynamically load and use Clockify tools as needed
8

Configure the agent with the MCP URL

const client = new MultiServerMCPClient({
    "clockify-agent": {
        transport: "http",
        url: url,
        headers: {
            "x-api-key": process.env.COMPOSIO_API_KEY
        }
    }
});

const tools = await client.getTools();

const agent = createAgent({ model: "gpt-5", tools });
What's happening:
  • We're creating a MultiServerMCPClient that connects to our Clockify MCP server via HTTP
  • The client is configured with a name and the URL from our Tool Router session
  • getTools() retrieves all available Clockify tools that the agent can use
  • We're creating a LangChain agent using the GPT-5 model
9

Set up interactive chat interface

let conversationHistory: any[] = [];

console.log("Chat started! Type 'exit' or 'quit' to end the conversation.\n");
console.log("Ask any Clockify related question or task to the agent.\n");

const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: 'You: '
});

rl.prompt();

rl.on('line', async (userInput: string) => {
    const trimmedInput = userInput.trim();

    if (['exit', 'quit', 'bye'].includes(trimmedInput.toLowerCase())) {
        console.log("\nGoodbye!");
        rl.close();
        process.exit(0);
    }

    if (!trimmedInput) {
        rl.prompt();
        return;
    }

    conversationHistory.push({ role: "user", content: trimmedInput });
    console.log("\nAgent is thinking...\n");

    const response = await agent.invoke({ messages: conversationHistory });
    conversationHistory = response.messages;

    const finalResponse = response.messages[response.messages.length - 1]?.content;
    console.log(`Agent: ${finalResponse}\n`);
        
        rl.prompt();
    });

    rl.on('close', () => {
        console.log('\n👋 Session ended.');
        process.exit(0);
    });
What's happening:
  • We initialize an empty conversationHistory list to maintain context across interactions
  • A readline interface is used to continuously accept user input from the command line
  • When a user types a message, it's added to the conversation history and sent to the agent
  • The agent processes the request using the invoke() method with the full conversation history
  • Users can type 'exit', 'quit', or 'bye' to end the chat session gracefully
10

Run the application

main().catch((err) => {
    console.error('Fatal error:', err);
    process.exit(1);
});
What's happening:
  • We call the main() function to start the application

Complete Code

Here's the complete code to get you started with Clockify and LangChain:

import { Composio } from '@composio/core';
import { LangchainProvider } from '@composio/langchain';
import { MultiServerMCPClient } from "@langchain/mcp-adapters";  
import { createAgent } from "langchain";
import * as readline from 'readline';
import 'dotenv/config';

const composioApiKey = process.env.COMPOSIO_API_KEY;
const userId = process.env.COMPOSIO_USER_ID;

if (!composioApiKey) throw new Error('COMPOSIO_API_KEY is not set');
if (!userId) throw new Error('COMPOSIO_USER_ID is not set');

async function main() {
    const composio = new Composio({
        apiKey: composioApiKey as string,
        provider: new LangchainProvider()
    });

    const session = await composio.create(
        userId as string,
        {
            toolkits: ['clockify']
        }
    );

    const url = session.mcp.url;
    
    const client = new MultiServerMCPClient({
        "clockify-agent": {
            transport: "http",
            url: url,
            headers: {
                "x-api-key": process.env.COMPOSIO_API_KEY
            }
        }
    });
    
    const tools = await client.getTools();
  
    const agent = createAgent({ model: "gpt-5", tools });
    
    let conversationHistory: any[] = [];
    
    console.log("Chat started! Type 'exit' or 'quit' to end the conversation.\n");
    console.log("Ask any Clockify related question or task to the agent.\n");
    
    const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout,
        prompt: 'You: '
    });

    rl.prompt();

    rl.on('line', async (userInput: string) => {
        const trimmedInput = userInput.trim();
        
        if (['exit', 'quit', 'bye'].includes(trimmedInput.toLowerCase())) {
            console.log("\nGoodbye!");
            rl.close();
            process.exit(0);
        }
        
        if (!trimmedInput) {
            rl.prompt();
            return;
        }
        
        conversationHistory.push({ role: "user", content: trimmedInput });
        console.log("\nAgent is thinking...\n");
        
        const response = await agent.invoke({ messages: conversationHistory });
        conversationHistory = response.messages;
        
        const finalResponse = response.messages[response.messages.length - 1]?.content;
        console.log(`Agent: ${finalResponse}\n`);
        
        rl.prompt();
    });

    rl.on('close', () => {
        console.log('\nSession ended.');
        process.exit(0);
    });
}

main().catch((err) => {
    console.error('Fatal error:', err);
    process.exit(1);
});

Conclusion

You've successfully built a LangChain agent that can interact with Clockify through Composio's Tool Router.

Key features of this implementation:

  • Dynamic tool loading through Composio's Tool Router
  • Conversation history maintenance for context-aware responses
  • Async Python provides clean, efficient execution of agent workflows
You can extend this further by adding error handling, implementing specific business logic, or integrating additional Composio toolkits to create multi-app workflows.
TOOLS

Supported Tools

Every Clockify action and event your agent gets out of the box.

Add User to Group

Tool to add a user to a user group in a Clockify workspace.

Create Client

Tool to add a new client to a workspace.

Create New Project

Create a project in a Clockify workspace with a name and optional color, billable status, and client association.

Create Shared Report

Create a shared summary, detailed, or weekly report with a date range and summary grouping options in a Clockify workspace.

Create Tag

Create a named tag in a Clockify workspace.

Create Task

Tool to add a new task to a project in Clockify.

Create Templates On Workspace

Create one or more templates in a Clockify workspace with associated projects and optional time entries.

Create Time Entry

Tool to create a new time entry in a Clockify workspace.

Create User Group

Tool to create a new user group in a workspace.

Create User Time Entry

Tool to create a time entry for another user in a Clockify workspace.

Create Webhook

Tool to create a new webhook in a workspace.

Create Workspace

Creates a new Clockify workspace for time tracking and project management in the specified organization.

Delete Client

Deletes a client from a Clockify workspace.

Delete Project

Tool to delete a project from a workspace.

Delete Shared Report

Tool to delete a shared report from a workspace by ID.

Delete Tag

Tool to delete a tag from a Clockify workspace.

Delete Task

Tool to delete a task from a project in Clockify.

Delete Template

Delete a template from a Clockify workspace using the deprecated template API.

Delete Time Entry

Tool to delete a time entry from a workspace by ID.

Delete User Group

Tool to delete a user group from a workspace.

Delete User Time Entries

Tool to delete multiple time entries for a user in a workspace.

Delete Webhook

Tool to delete a webhook from a workspace.

Duplicate Time Entry

Tool to duplicate an existing time entry in a Clockify workspace.

Filter Workspace Users

Tool to filter users in a workspace by advanced criteria.

Find User's Team Managers

Retrieves the list of team managers assigned to a specific user in a Clockify workspace.

Generate Detailed Report

Generates a detailed time-entry report with filtering and pagination for a workspace.

Generate Expense Report

Generate a detailed expense report for a workspace and date range, limited to 31 days on the free plan.

Generate New Webhook Token

Generate a new token for a workspace webhook, invalidating its previous token.

Generate Summary Report

Generate a workspace time-entry summary report grouped by projects, users, clients, or other criteria.

Generate Weekly Report

Generate a weekly workspace time-entry report with breakdowns grouped by user, project, task, or other dimensions.

Get All Addon Webhooks

Tool to list all webhooks for an addon in a workspace.

Get All My Workspaces

Lists workspaces accessible to the authenticated user, optionally filtered by roles.

Get All Webhooks

Tool to list all webhooks in a workspace.

Get Client By ID

Retrieves detailed information about a specific client in a Clockify workspace.

Get Clients

Tool to list clients in a workspace.

Get Created Entities

Retrieves created entities of a specified type in a workspace using the experimental API.

Get Currently Logged In User Info

Tool to retrieve info about the authenticated user.

Get Deleted Entities

Requests deleted entities of a specified type in a workspace through the experimental API.

Get Holidays

Tool to retrieve all holidays for a workspace.

Get Holidays In Period

Tool to retrieve holidays in a specific period.

Get In Progress Time Entries

Retrieve a page of currently running time entries in a workspace to check active timers and who is tracking time.

Get member's profile

Tool to get a member's profile in a workspace.

Get Project

Tool to retrieve detailed information about a specific project by ID.

Get Projects

Tool to list projects in a workspace with filtering and pagination.

Get Shared Report

Generate a shared report by ID using the Clockify Reports API.

Get Shared Reports

Retrieve the first page of shared reports for the current user in a Clockify workspace.

Get Tag By ID

Tool to retrieve detailed information about a specific tag by ID in a Clockify workspace.

Get Tags

List a page of workspace tags, optionally filtering by name or archived status.

Get Task

Retrieves detailed information about a specific task in a Clockify project.

Get Tasks

List, search, or filter a page of tasks on a specific project in a workspace.

Get Templates On Workspace

List a page of templates in a Clockify workspace, optionally filtered by name.

Get Time Entries

Tool to retrieve historical time entries for a user in a workspace with filters.

Get Time Entry

Tool to retrieve a specific time entry by ID from a workspace.

Get Updated Entities

Retrieve updated workspace entities using the experimental API for one supported type: time entries, time entry rates, time entry custom field values, or custom fields.

Get User Groups

List a page of user groups in a workspace.

Get Webhook By ID

Retrieves detailed information about a specific webhook in a Clockify workspace.

Get Webhook Logs

Tool to retrieve webhook logs for a specific webhook.

Get Workspace Info

Retrieves detailed information about a specific Clockify workspace.

List Assignments

Lists a page of scheduling assignments in a workspace, starting from a specified date and optionally bounded by an end date.

Remove User From Group

Remove a user from a Clockify user group.

Stop User Timer

Tool to stop a currently running timer for a user in a workspace.

Update Client

Updates a client in a Clockify workspace, including details such as name, email, address, or archived status.

Update Project

Tool to update an existing project in a Clockify workspace.

Update Project Memberships

Tool to update project memberships in Clockify.

Update Project User Hourly Rate

Tool to update a project user's billable rate.

Update Shared Report

Update a shared report's name, public visibility, and fixed-date setting in Clockify.

Update Tag

Tool to update a tag in a Clockify workspace.

Update Task

Tool to update an existing task on a project in Clockify.

Update Time Entries

Bulk updates multiple time entries for a specified user in a Clockify workspace, including start/end times, descriptions, billable status, and project or task associations.

Update Time Entry

Tool to update an existing time entry in a Clockify workspace.

Update User Group

Tool to update an existing user group in a workspace.

Update User Hourly Rate

Tool to update a user's hourly rate in a Clockify workspace.

Update Webhook

Updates a workspace webhook's configuration, including its name, URL, event type, and trigger sources.

Update Workspace Hourly Rate

Tool to update the workspace billable hourly rate.

FRAMEWORKS

How to build Clockify MCP Agent with another framework

Claude Code logo

Claude Code

Use Clockify MCP with Claude Code

Claude Cowork logo

Claude Cowork

Use Clockify MCP with Claude Cowork

OpenAI Agents SDK logo

OpenAI Agents SDK

Use Clockify MCP with OpenAI Agents SDK

Claude Agent SDK logo

Claude Agent SDK

Use Clockify MCP with Claude Agent SDK

Codex logo

Codex

Use Clockify MCP with Codex

OpenClaw logo

OpenClaw

Use Clockify MCP with OpenClaw

Hermes logo

Hermes

Use Clockify MCP with Hermes

Atomic Agent logo

Atomic Agent

Use Clockify MCP with Atomic Agent

Google ADK logo

Google ADK

Use Clockify MCP with Google ADK

Vercel AI SDK logo

Vercel AI SDK

Use Clockify MCP with Vercel AI SDK

Mastra AI logo

Mastra AI

Use Clockify MCP with Mastra AI

LlamaIndex logo

LlamaIndex

Use Clockify MCP with LlamaIndex

CrewAI logo

CrewAI

Use Clockify MCP with CrewAI

Pydantic AI logo

Pydantic AI

Use Clockify MCP with Pydantic AI

AutoGen logo

AutoGen

Use Clockify MCP with AutoGen

FAQ

Frequently asked questions

Start with Clockify.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Clockify tool your agent needs.Free to start.

Start building