Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:1257-1284 (handler)

  The main handler function for the 'get_clients' tool. It constructs a query to the Clockify API endpoint `/workspaces/{workspaceId}/clients` with optional filters (archived, name, page, pageSize), fetches the clients, and returns a formatted text response listing them.

  private async getClients(args: any) {
    const { workspaceId, ...params } = args;
  
    const queryParams = new URLSearchParams();
    Object.entries(params).forEach(([key, value]) => {
      if (value !== undefined && value !== null) {
        queryParams.append(key, String(value));
      }
    });
  
    const endpoint = queryParams.toString()
      ? `/workspaces/${workspaceId}/clients?${queryParams.toString()}`
      : `/workspaces/${workspaceId}/clients`;
  
    const clients = await this.makeRequest(endpoint);
  
    return {
      content: [
        {
          type: "text",
          text: `Found ${clients.length} client(s):\n${clients
            .map((c: any) => `- ${c.name} (${c.id}) | Archived: ${c.archived}`)
            .join("\n")}`,
        },
      ],
      isError: false,
    };
  }

• src/index.ts:788-790 (registration)

  Registration of the 'get_clients' tool handler in the CallToolRequestSchema switch statement, which dispatches to the getClients method.

  case "get_clients":
    if (!args?.workspaceId) throw new McpError(ErrorCode.InvalidParams, 'workspaceId is required');
    return await this.getClients(args as any);

• src/index.ts:564-578 (schema)

  Tool schema definition including name, description, and input schema registered in the ListToolsRequestSchema response.

  {
    name: "get_clients",
    description: "Get all clients in a workspace",
    inputSchema: {
      type: "object",
      properties: {
        workspaceId: { type: "string", description: "Workspace ID" },
        archived: { type: "boolean", description: "Filter by archived status" },
        name: { type: "string", description: "Filter by client name" },
        page: { type: "number", description: "Page number (default: 1)" },
        pageSize: { type: "number", description: "Page size (default: 50, max: 5000)" },
      },
      required: ["workspaceId"],
    },
  },

• src/index.ts:51-56 (schema)

  TypeScript interface defining the Client object structure used by the get_clients tool.

  interface Client {
    id?: string;
    name: string;
    workspaceId: string;
    archived?: boolean;
  }