Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:1082-1094 (handler)

  The main handler function that retrieves a specific project by its ID from the Clockify API endpoint `/workspaces/{workspaceId}/projects/{projectId}` and formats the response as MCP content.

  private async getProject(workspaceId: string, projectId: string) {
    const project = await this.makeRequest(`/workspaces/${workspaceId}/projects/${projectId}`);
  
    return {
      content: [
        {
          type: "text",
          text: `Project Details:\nName: ${project.name}\nID: ${project.id}\nClient: ${project.clientName || "No client"}\nPublic: ${project.public}\nBillable: ${project.billable}\nColor: ${project.color}\nArchived: ${project.archived}`,
        },
      ],
      isError: false,
    };
  }

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

  Registration of the 'get_project' tool in the CallToolRequestSchema handler switch statement, which validates parameters and delegates to the getProject method.

  case "get_project":
    if (!args?.workspaceId || !args?.projectId) throw new McpError(ErrorCode.InvalidParams, 'workspaceId and projectId are required');
    return await this.getProject(args.workspaceId as string, args.projectId as string);

• src/index.ts:431-441 (schema)

  Tool schema definition and registration in the ListToolsRequestSchema response, including name, description, and input schema for the 'get_project' tool.

    name: "get_project",
    description: "Get a specific project by ID",
    inputSchema: {
      type: "object",
      properties: {
        workspaceId: { type: "string", description: "Workspace ID" },
        projectId: { type: "string", description: "Project ID" },
      },
      required: ["workspaceId", "projectId"],
    },
  },

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

  TypeScript interface defining the structure of a Project object, used in the tool's response handling.

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