Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:1053-1080 (handler)

  The core handler function for the 'get_projects' tool. It builds query parameters from input args, calls the Clockify API to fetch projects from /workspaces/{workspaceId}/projects, and formats a response listing the projects with name, ID, client, and billable status.

  private async getProjects(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}/projects?${queryParams.toString()}`
      : `/workspaces/${workspaceId}/projects`;
  
    const projects = await this.makeRequest(endpoint);
  
    return {
      content: [
        {
          type: "text",
          text: `Found ${projects.length} project(s):\n${projects
            .map((p: any) => `- ${p.name} (${p.id}) | Client: ${p.clientName || "None"} | Billable: ${p.billable}`)
            .join("\n")}`,
        },
      ],
      isError: false,
    };
  }

• src/index.ts:408-428 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining the name, description, and detailed inputSchema for parameters like workspaceId, filters, sorting, and pagination.

  {
    name: "get_projects",
    description: "Get all projects 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 project name" },
        clientIds: { type: "string", description: "Filter by client IDs (comma-separated)" },
        containsClient: { type: "boolean", description: "Filter projects that have clients" },
        clientStatus: { type: "string", enum: ["ACTIVE", "ARCHIVED"], description: "Filter by client status" },
        users: { type: "string", description: "Filter by user IDs (comma-separated)" },
        isTemplate: { type: "boolean", description: "Filter by template status" },
        sortColumn: { type: "string", description: "Sort column" },
        sortOrder: { type: "string", enum: ["ASCENDING", "DESCENDING"], description: "Sort order" },
        page: { type: "number", description: "Page number (default: 1)" },
        pageSize: { type: "number", description: "Page size (default: 50, max: 5000)" },
      },
      required: ["workspaceId"],
    },

• src/index.ts:755-757 (registration)

  Dispatch logic in the CallToolRequestSchema switch statement that validates workspaceId and invokes the getProjects handler.

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

• src/index.ts:28-40 (schema)

  TypeScript interface defining the structure of a Project object, used throughout the codebase for type safety.

  interface Project {
    id?: string;
    name: string;
    clientId?: string;
    workspaceId: string;
    isPublic?: boolean;
    billable?: boolean;
    color?: string;
    estimate?: {
      estimate: string;
      type: "AUTO" | "MANUAL";
    };
  }