get_projects
Retrieve all projects from a Clockify workspace with filtering options for archived status, name, clients, users, templates, and sorting preferences.
Instructions
Get all projects in a workspace
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceId | Yes | Workspace ID | |
| archived | No | Filter by archived status | |
| name | No | Filter by project name | |
| clientIds | No | Filter by client IDs (comma-separated) | |
| containsClient | No | Filter projects that have clients | |
| clientStatus | No | Filter by client status | |
| users | No | Filter by user IDs (comma-separated) | |
| isTemplate | No | Filter by template status | |
| sortColumn | No | Sort column | |
| sortOrder | No | Sort order | |
| page | No | Page number (default: 1) | |
| pageSize | No | Page size (default: 50, max: 5000) |
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"; }; }