ClickUp MCP Server

Instructions

Implementation Reference

• src/clickup_mcp/tools.py:764-791 (handler)

  The primary handler for the 'search_tasks' MCP tool. It invokes the client's search_tasks method with provided filters and returns a formatted dictionary containing the list of matching tasks with key details like ID, name, status, list, space, and URL.
  async def search_tasks( self, query: Optional[str] = None, statuses: Optional[List[str]] = None, assignees: Optional[List[int]] = None, **kwargs: Any, ) -> Dict[str, Any]: """Search tasks.""" tasks = await self.client.search_tasks( query=query, statuses=statuses, assignees=assignees, ) return { "tasks": [ { "id": task.id, "name": task.name, "status": task.status.status, "list": task.list.get("name", "Unknown"), "space": task.space.get("name", "Unknown"), "url": format_task_url(task.id), } for task in tasks ], "count": len(tasks), }
• src/clickup_mcp/tools.py:177-196 (schema)

  The JSON schema definition for the 'search_tasks' tool input, specifying optional parameters: query (string), statuses (array of strings), and assignees (array of integers).
  Tool( name="search_tasks", description="Search tasks across workspace", inputSchema={ "type": "object", "properties": { "query": {"type": "string", "description": "Search query"}, "statuses": { "type": "array", "items": {"type": "string"}, "description": "Filter by statuses", }, "assignees": { "type": "array", "items": {"type": "integer"}, "description": "Filter by assignee IDs", }, }, }, ),
• src/clickup_mcp/tools.py:22-58 (registration)

  Registration of all tools including 'search_tasks' in the ClickUpTools class _tools dictionary, mapping tool names to their handler methods. This dictionary is used by call_tool to dispatch invocations.
  self.client = client 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/client.py:364-409 (helper)

  Supporting helper method in ClickUpClient that performs the actual HTTP API request to ClickUp's /team/{workspace_id}/task endpoint with search parameters and parses the response into Task objects.
  async def search_tasks( self, workspace_id: Optional[str] = None, query: Optional[str] = None, statuses: Optional[List[str]] = None, assignees: Optional[List[int]] = None, tags: Optional[List[str]] = None, date_created_gt: Optional[int] = None, date_created_lt: Optional[int] = None, date_updated_gt: Optional[int] = None, date_updated_lt: Optional[int] = None, ) -> List[Task]: """Search tasks across the workspace.""" workspace_id = workspace_id or self.config.default_workspace_id if not workspace_id: workspaces = await self.get_workspaces() if not workspaces: raise ClickUpAPIError("No workspaces found") workspace_id = workspaces[0].id params: Dict[str, Any] = {} if query: params["query"] = query if statuses: params["statuses[]"] = statuses if assignees: params["assignees[]"] = assignees if tags: params["tags[]"] = tags if date_created_gt: params["date_created_gt"] = str(date_created_gt) if date_created_lt: params["date_created_lt"] = str(date_created_lt) if date_updated_gt: params["date_updated_gt"] = str(date_updated_gt) if date_updated_lt: params["date_updated_lt"] = str(date_updated_lt) data = await self._request( "GET", f"/team/{workspace_id}/task", params=params, ) tasks = data.get("tasks", []) return [Task(**task) for task in tasks]
• src/clickup_mcp/server.py:41-45 (registration)

  MCP server handler for listing tools, which returns the tool definitions from ClickUpTools including the 'search_tasks' tool schema and makes it discoverable to MCP clients.
  @self.server.list_tools() async def list_tools() -> List[Tool]: """List all available tools.""" return self.tools.get_tool_definitions()