get_projects
Retrieve and filter projects within a specific workspace using filters like archived status, project name, client IDs, user IDs, and sorting options to streamline project management on the Clockify MCP Server.
Instructions
Get all projects in a workspace
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No | Filter by archived status | |
| clientIds | No | Filter by client IDs (comma-separated) | |
| clientStatus | No | Filter by client status | |
| containsClient | No | Filter projects that have clients | |
| isTemplate | No | Filter by template status | |
| name | No | Filter by project name | |
| page | No | Page number (default: 1) | |
| pageSize | No | Page size (default: 50, max: 5000) | |
| sortColumn | No | Sort column | |
| sortOrder | No | Sort order | |
| users | No | Filter by user IDs (comma-separated) | |
| workspaceId | Yes | Workspace ID |
Implementation Reference
- src/index.ts:1053-1080 (handler)The handler function for the 'get_projects' tool. It constructs the API endpoint for fetching projects from a Clockify workspace with optional query parameters, calls the makeRequest method, and returns a formatted text list of projects.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:411-426 (schema)Input schema defining parameters for the 'get_projects' tool, including required workspaceId and optional filters for projects.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)" }, },
- src/index.ts:409-429 (registration)Registers the 'get_projects' tool in the ListToolsRequestSchema response, including name, description, and schema.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:754-756 (registration)Registers the handler dispatch for 'get_projects' in the CallToolRequestSchema switch statement.case "get_projects": if (!args?.workspaceId) throw new McpError(ErrorCode.InvalidParams, 'workspaceId is required'); return await this.getProjects(args as any);
- src/index.ts:28-40 (schema)TypeScript interface defining the Project data structure used in the tool's responses.interface Project { id?: string; name: string; clientId?: string; workspaceId: string; isPublic?: boolean; billable?: boolean; color?: string; estimate?: { estimate: string; type: "AUTO" | "MANUAL"; }; }