ClickUp MCP Server

Instructions

Implementation Reference

• src/clickup_mcp/tools.py:1005-1018 (handler)

  The primary handler function for the MCP tool 'find_list_by_name'. It invokes the ClickUp client method and returns a formatted dictionary response or error.
  async def find_list_by_name(self, name: str, space_id: Optional[str] = None) -> Dict[str, Any]: """Find list by name.""" lst = await self.client.find_list_by_name(name, space_id) if not lst: return {"error": f"List '{name}' not found"} return { "id": lst.id, "name": lst.name, "space": lst.space.get("name", "Unknown"), "folder": lst.folder.get("name") if lst.folder else None, "found": True, }
• src/clickup_mcp/tools.py:319-330 (schema)

  The input schema definition for the 'find_list_by_name' tool, defining parameters 'name' (required) and 'space_id' (optional).
  Tool( name="find_list_by_name", description="Find a list by name", inputSchema={ "type": "object", "properties": { "name": {"type": "string", "description": "List name to search for"}, "space_id": {"type": "string", "description": "Space ID to search in"}, }, "required": ["name"], }, ),
• src/clickup_mcp/client.py:240-270 (helper)

  The underlying ClickUpClient helper method that performs the actual API calls to search for lists by name, recursively checking spaces and folders.
  async def find_list_by_name( self, name: str, space_id: Optional[str] = None, ) -> Optional[ClickUpList]: """Find a list by name in a space.""" if not space_id: # Search in all spaces if not specified spaces = await self.get_spaces() for space in spaces: result = await self.find_list_by_name(name, space.id) if result: return result return None # Get all lists in the space lists = await self.get_lists(space_id=space_id) # Also check folders folders = await self.get_folders(space_id) for folder in folders: folder_lists = await self.get_lists(folder_id=folder.id) lists.extend(folder_lists) # Find by name (case-insensitive) name_lower = name.lower() for lst in lists: if lst.name.lower() == name_lower: return lst return None
• src/clickup_mcp/tools.py:23-57 (registration)

  The internal _tools dictionary in ClickUpTools class maps the tool name 'find_list_by_name' to its handler function, used by call_tool for dispatching.
  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: the list_tools handler returns all tool definitions including 'find_list_by_name' 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()