Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:270-279 (registration)

  Registers the 'get_workspace_users' tool in the list of available tools, including its name, description, and input schema requiring 'workspaceId'.

    name: "get_workspace_users",
    description: "Get all users in a workspace",
    inputSchema: {
      type: "object",
      properties: {
        workspaceId: { type: "string", description: "Workspace ID" },
      },
      required: ["workspaceId"],
    },
  },

• src/index.ts:726-728 (registration)

  Dispatches calls to the 'get_workspace_users' tool handler by invoking getWorkspaceUsers method after input validation.

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

• src/index.ts:865-878 (handler)

  The main handler function that fetches users from the Clockify API endpoint `/workspaces/${workspaceId}/users`, processes them using the User type, and returns a formatted text response listing the users.

  private async getWorkspaceUsers(workspaceId: string | undefined) {
    const users = await this.makeRequest(`/workspaces/${workspaceId}/users`);
    return {
      content: [
        {
          type: "text",
          text: `Found ${users.length} user(s) in workspace:\n${users
            .map((u: User) => `- ${u.name} (${u.email}) - ${u.id}`)
            .join("\n")}`,
        },
      ],
      isError: false,
    };
  }

• src/index.ts:58-114 (schema)

  TypeScript interface defining the User object structure used in processing the API response for workspace users.

  interface User {
    id: string;
    email: string;
    name: string;
    memberships: Array<{
      userId: string;
      hourlyRate?: {
        amount: number;
        currency: string;
      };
      costRate?: {
        amount: number;
        currency: string;
      };
      targetId: string;
      membershipType: "WORKSPACE" | "PROJECT";
      membershipStatus: "PENDING" | "ACTIVE" | "DECLINED" | "INACTIVE";
    }>;
    profilePicture?: string;
    activeWorkspace: string;
    defaultWorkspace: string;
    settings: {
      weekStart: string;
      timeZone: string;
      timeFormat: string;
      dateFormat: string;
      sendNewsletter: boolean;
      weeklyUpdates: boolean;
      longRunning: boolean;
      timeTrackingManual: boolean;
      summaryReportSettings: {
        group: string;
        subgroup: string;
      };
      isCompactViewOn: boolean;
      dashboardSelection: string;
      dashboardViewType: string;
      dashboardPinToTop: boolean;
      projectListCollapse: number;
      collapseAllProjectLists: boolean;
      groupSimilarEntriesDisabled: boolean;
      myStartOfDay: string;
      projectPickerTaskFilter: boolean;
      lang: string;
      multiFactorEnabled: boolean;
      theme: string;
      scheduling: boolean;
      onboarding: boolean;
      pto: boolean;
    };
    status: string;
    customFields: Array<{
      customFieldId: string;
      sourceType: string;
      value: string;
    }>;
  }