Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:1472-1521 (handler)

  The handler function that implements the get_summary_report tool. It constructs a payload for the Clockify summary reports API, sends a POST request to /reports/summary, and returns a formatted summary of the report.

    private async getSummaryReport(args: any) {
      const { workspaceId, ...reportData } = args;
  
      const payload = {
        dateRangeStart: reportData.dateRangeStart,
        dateRangeEnd: reportData.dateRangeEnd,
        summaryFilter: {
          groups: reportData.groups || ["PROJECT"],
          sortColumn: reportData.sortColumn || "DURATION",
          sortOrder: reportData.sortOrder || "DESCENDING",
        },
        users: reportData.users ? { ids: reportData.users } : undefined,
        clients: reportData.clients ? { ids: reportData.clients } : undefined,
        projects: reportData.projects ? { ids: reportData.projects } : undefined,
        tasks: reportData.tasks ? { ids: reportData.tasks } : undefined,
        tags: reportData.tags ? { ids: reportData.tags } : undefined,
        billable: reportData.billable,
        exportType: reportData.exportType || "JSON",
      };
  
      // Remove undefined properties
      Object.keys(payload).forEach(key => {
        if (payload[key as keyof typeof payload] === undefined) {
          delete payload[key as keyof typeof payload];
        }
      });
  
      const report = await this.makeRequest(
        `/workspaces/${workspaceId}/reports/summary`,
        "POST",
        payload,
        "https://reports.api.clockify.me/v1"
      );
  
      const summary = `Summary Report:
  Groups: ${reportData.groups?.join(", ") || "PROJECT"}
  Total Duration: ${report.totals?.[0]?.totalTime || "0:00:00"}
  Date Range: ${reportData.dateRangeStart} to ${reportData.dateRangeEnd}
  Group Count: ${report.groupOne?.length || 0}`;
  
      return {
        content: [
          {
            type: "text",
            text: summary,
          },
        ],
        isError: false,
      };
    }

• src/index.ts:693-711 (schema)

  The input schema defining parameters for the get_summary_report tool, including required workspaceId, date range, and optional filters.

  inputSchema: {
    type: "object",
    properties: {
      workspaceId: { type: "string", description: "Workspace ID" },
      dateRangeStart: { type: "string", description: "Start date (ISO 8601 format)" },
      dateRangeEnd: { type: "string", description: "End date (ISO 8601 format)" },
      users: { type: "array", items: { type: "string" }, description: "Array of user IDs to filter" },
      clients: { type: "array", items: { type: "string" }, description: "Array of client IDs to filter" },
      projects: { type: "array", items: { type: "string" }, description: "Array of project IDs to filter" },
      tasks: { type: "array", items: { type: "string" }, description: "Array of task IDs to filter" },
      tags: { type: "array", items: { type: "string" }, description: "Array of tag IDs to filter" },
      billable: { type: "boolean", description: "Filter by billable status" },
      groups: { type: "array", items: { type: "string" }, description: "Group by fields (USER, PROJECT, CLIENT, etc.)" },
      sortColumn: { type: "string", description: "Sort column" },
      sortOrder: { type: "string", enum: ["ASCENDING", "DESCENDING"], description: "Sort order" },
      exportType: { type: "string", enum: ["JSON", "PDF", "CSV", "XLSX"], description: "Export format" },
    },
    required: ["workspaceId", "dateRangeStart", "dateRangeEnd"],
  },

• src/index.ts:690-712 (registration)

  Tool registration in the list of available tools, including name, description, and input schema.

  {
    name: "get_summary_report",
    description: "Generate a summary time tracking report",
    inputSchema: {
      type: "object",
      properties: {
        workspaceId: { type: "string", description: "Workspace ID" },
        dateRangeStart: { type: "string", description: "Start date (ISO 8601 format)" },
        dateRangeEnd: { type: "string", description: "End date (ISO 8601 format)" },
        users: { type: "array", items: { type: "string" }, description: "Array of user IDs to filter" },
        clients: { type: "array", items: { type: "string" }, description: "Array of client IDs to filter" },
        projects: { type: "array", items: { type: "string" }, description: "Array of project IDs to filter" },
        tasks: { type: "array", items: { type: "string" }, description: "Array of task IDs to filter" },
        tags: { type: "array", items: { type: "string" }, description: "Array of tag IDs to filter" },
        billable: { type: "boolean", description: "Filter by billable status" },
        groups: { type: "array", items: { type: "string" }, description: "Group by fields (USER, PROJECT, CLIENT, etc.)" },
        sortColumn: { type: "string", description: "Sort column" },
        sortOrder: { type: "string", enum: ["ASCENDING", "DESCENDING"], description: "Sort order" },
        exportType: { type: "string", enum: ["JSON", "PDF", "CSV", "XLSX"], description: "Export format" },
      },
      required: ["workspaceId", "dateRangeStart", "dateRangeEnd"],
    },
  },

• src/index.ts:813-816 (registration)

  Dispatch/registration in the CallToolRequestSchema handler switch statement that routes calls to the getSummaryReport method.

  case "get_detailed_report":
    return await this.getDetailedReport(args);
  case "get_summary_report":
    return await this.getSummaryReport(args);