ClickUp MCP Server

Instructions

Implementation Reference

• src/clickup_mcp/tools.py:1253-1299 (handler)

  The handler function that implements get_team_workload. Fetches all tasks in a space using the client, groups them by assignee username, counts tasks per user, sums time estimates, tracks by priority, converts estimates to hours, and returns workload stats including unassigned tasks.

  async def get_team_workload(
      self, space_id: str, include_completed: bool = False
  ) -> Dict[str, Any]:
      """Get workload distribution across team members."""
      # Get all tasks in the space
      tasks = await self.client.get_tasks(
          space_id=space_id,
          include_closed=include_completed,
      )
  
      # Group by assignee
      workload = {}
      unassigned_count = 0
  
      for task in tasks:
          if not task.assignees:
              unassigned_count += 1
          else:
              for assignee in task.assignees:
                  username = assignee.username
                  if username not in workload:
                      workload[username] = {
                          "user_id": assignee.id,
                          "username": username,
                          "task_count": 0,
                          "total_time_estimate": 0,
                          "by_priority": {1: 0, 2: 0, 3: 0, 4: 0},
                      }
  
                  workload[username]["task_count"] += 1
                  if task.time_estimate:
                      workload[username]["total_time_estimate"] += task.time_estimate
                  if task.priority:
                      workload[username]["by_priority"][task.priority.value] += 1
  
      # Convert time estimates to hours
      for user_data in workload.values():
          user_data["total_hours_estimate"] = round(
              user_data["total_time_estimate"] / (1000 * 60 * 60), 2
          )
  
      return {
          "space_id": space_id,
          "team_workload": list(workload.values()),
          "unassigned_tasks": unassigned_count,
          "total_tasks": len(tasks),
      }

• src/clickup_mcp/tools.py:438-452 (schema)

  Input schema definition for the get_team_workload tool, specifying required space_id and optional include_completed boolean.

  Tool(
      name="get_team_workload",
      description="Get workload distribution across team members",
      inputSchema={
          "type": "object",
          "properties": {
              "space_id": {"type": "string", "description": "Space ID"},
              "include_completed": {
                  "type": "boolean",
                  "description": "Include completed tasks in analysis",
              },
          },
          "required": ["space_id"],
      },
  ),

• src/clickup_mcp/tools.py:23-57 (registration)

  Registration of the get_team_workload handler method in the ClickUpTools class's _tools dictionary, mapping the tool name to its implementation.

  self._tools: Dict[str, Callable] = {
      "create_task": self.create_task,
      "get_task": self.get_task,
      "update_task": self.update_task,
      "delete_task": self.delete_task,
      "list_tasks": self.list_tasks,
      "search_tasks": self.search_tasks,
      "get_subtasks": self.get_subtasks,
      "get_task_comments": self.get_task_comments,
      "create_task_comment": self.create_task_comment,
      "get_task_status": self.get_task_status,
      "update_task_status": self.update_task_status,
      "get_assignees": self.get_assignees,
      "assign_task": self.assign_task,
      "list_spaces": self.list_spaces,
      "list_folders": self.list_folders,
      "list_lists": self.list_lists,
      "find_list_by_name": self.find_list_by_name,
      # Bulk operations
      "bulk_update_tasks": self.bulk_update_tasks,
      "bulk_move_tasks": self.bulk_move_tasks,
      # Time tracking
      "get_time_tracked": self.get_time_tracked,
      "log_time": self.log_time,
      # Templates
      "create_task_from_template": self.create_task_from_template,
      "create_task_chain": self.create_task_chain,
      # Analytics
      "get_team_workload": self.get_team_workload,
      "get_task_analytics": self.get_task_analytics,
      # User management
      "list_users": self.list_users,
      "get_current_user": self.get_current_user,
      "find_user_by_name": self.find_user_by_name,
  }

• src/clickup_mcp/server.py:41-59 (registration)

  MCP server registration: the list_tools handler exposes all tool definitions from ClickUpTools including get_team_workload.

  @self.server.list_tools()
  async def list_tools() -> List[Tool]:
      """List all available tools."""
      return self.tools.get_tool_definitions()
  
  @self.server.call_tool()
  async def call_tool(
      name: str, arguments: Optional[Dict[str, Any]] = None
  ) -> List[TextContent | ImageContent | EmbeddedResource]:
      """Call a specific tool."""
      logger.debug(f"Calling tool: {name} with arguments: {arguments}")
  
      try:
          result = await self.tools.call_tool(name, arguments or {})
          return [TextContent(type="text", text=result)]
      except Exception as e:
          logger.error(f"Error calling tool {name}: {e}", exc_info=True)
          return [TextContent(type="text", text=f"Error: {e!s}")]

• src/clickup_mcp/server.py:46-59 (registration)

  MCP server registration: the call_tool handler dispatches to ClickUpTools.call_tool, which invokes the specific get_team_workload handler based on name.

  @self.server.call_tool()
  async def call_tool(
      name: str, arguments: Optional[Dict[str, Any]] = None
  ) -> List[TextContent | ImageContent | EmbeddedResource]:
      """Call a specific tool."""
      logger.debug(f"Calling tool: {name} with arguments: {arguments}")
  
      try:
          result = await self.tools.call_tool(name, arguments or {})
          return [TextContent(type="text", text=result)]
      except Exception as e:
          logger.error(f"Error calling tool {name}: {e}", exc_info=True)
          return [TextContent(type="text", text=f"Error: {e!s}")]