ClickUp MCP Server

Instructions

Implementation Reference

• src/clickup_mcp/tools.py:951-974 (handler)

  The handler function that implements the list_folders tool. It fetches folders using the ClickUpClient and returns a formatted JSON response with folder details including nested lists.

  async def list_folders(self, space_id: str) -> Dict[str, Any]:
      """List folders in space."""
      folders = await self.client.get_folders(space_id)
  
      return {
          "space_id": space_id,
          "folders": [
              {
                  "id": folder.id,
                  "name": folder.name,
                  "task_count": folder.task_count,
                  "lists": [
                      {
                          "id": lst.id,
                          "name": lst.name,
                          "task_count": lst.task_count,
                      }
                      for lst in folder.lists
                  ],
              }
              for folder in folders
          ],
          "count": len(folders),
      }

• src/clickup_mcp/tools.py:297-307 (schema)

  The Tool schema definition for list_folders, specifying the input schema that requires a space_id parameter.

  Tool(
      name="list_folders",
      description="List folders in a space",
      inputSchema={
          "type": "object",
          "properties": {
              "space_id": {"type": "string", "description": "Space ID"},
          },
          "required": ["space_id"],
      },
  ),

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

  Registration of the list_folders handler method in the internal _tools dictionary of ClickUpTools class, which is used by the call_tool method to dispatch calls.

  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-45 (registration)

  MCP server registration for listing tools, which returns the tool definitions (including list_folders schema) from ClickUpTools.get_tool_definitions().

  @self.server.list_tools()
  async def list_tools() -> List[Tool]:
      """List all available tools."""
      return self.tools.get_tool_definitions()

• src/clickup_mcp/client.py:206-211 (helper)

  Helper method in ClickUpClient that performs the actual API request to retrieve folders from a ClickUp space and parses them into Folder model objects.

  async def get_folders(self, space_id: str) -> List[Folder]:
      """Get all folders in a space."""
      data = await self._request("GET", f"/space/{space_id}/folder")
      folders = data.get("folders", [])
      return [Folder(**folder) for folder in folders]