Clockify MCP Server

Instructions

Implementation Reference

• src/index.ts:850-863 (handler)

  The handler function for the 'get_workspaces' tool. It makes an API request to fetch all workspaces for the current user and returns a formatted text response listing the workspace names and IDs.
  private async getWorkspaces() { const workspaces = await this.makeRequest("/workspaces"); return { content: [ { type: "text", text: `Found ${workspaces.length} workspace(s):\n${workspaces .map((w: Workspace) => `- ${w.name} (${w.id})`) .join("\n")}`, }, ], isError: false, }; }
• src/index.ts:261-268 (registration)

  Registers the 'get_workspaces' tool in the listTools response, providing its name, description, and input schema (no parameters required).
  { name: "get_workspaces", description: "Get all workspaces for the current user", inputSchema: { type: "object", properties: {}, }, },
• src/index.ts:724-725 (registration)

  In the CallToolRequestSchema handler, dispatches execution to the getWorkspaces method based on the tool name.
  case "get_workspaces": return await this.getWorkspaces();
• src/index.ts:116-176 (schema)

  TypeScript interface defining the structure of a Workspace object, used in typing the API response in the handler.
  interface Workspace { id: string; name: string; hourlyRate?: { amount: number; currency: 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"; }>; workspaceSettings: { timeRoundingInReports: boolean; onlyAdminsSeeBillableRates: boolean; onlyAdminsCreateProject: boolean; onlyAdminsSeeDashboard: boolean; defaultBillableProjects: boolean; lockTimeEntries?: string; round: { round: string; minutes: string; }; projectFavorites: boolean; canSeeTimeSheet: boolean; canSeeTracker: boolean; projectPickerSpecialFilter: boolean; forceProjects: boolean; forceTasks: boolean; forceTags: boolean; forceDescription: boolean; onlyAdminsSeeAllTimeEntries: boolean; onlyAdminsSeePublicProjectsEntries: boolean; trackTimeDownToSecond: boolean; projectGroupingLabel: string; adminOnlyPages: string[]; automaticLock?: { changeDay: string; dayOfMonth: number; firstDay: string; olderThanPeriod: string; olderThanValue: number; type: string; }; onlyAdminsCreateTag: boolean; onlyAdminsCreateTask: boolean; timeTrackingMode: string; isProjectPublicByDefault: boolean; }; imageUrl?: string; featureSubscriptionType?: string; }
• src/index.ts:203-247 (helper)

  Helper method used by getWorkspaces to make authenticated HTTP requests to the Clockify API.
  private async makeRequest( endpoint: string, method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" = "GET", data?: any, baseUrl?: string ): Promise<any> { if (!this.config.apiKey) { throw new McpError( ErrorCode.InvalidParams, "Clockify API key not configured. Set CLOCKIFY_API_KEY environment variable." ); } const url = `${baseUrl || this.config.baseUrl}${endpoint}`; const headers: Record<string, string> = { "X-Api-Key": this.config.apiKey, "Content-Type": "application/json", }; try { const response = await fetch(url, { method, headers, body: data ? JSON.stringify(data) : undefined, }); if (!response.ok) { const errorText = await response.text(); throw new McpError( ErrorCode.InternalError, `Clockify API error (${response.status}): ${errorText}` ); } return response.json(); } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Request failed: ${error instanceof Error ? error.message : String(error)}` ); } }