ClickUp MCP Server

Instructions

Implementation Reference

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

  Implementation of the search_tasks tool handler. Calls the ClickUp client's search_tasks method and formats the response with task details including 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)

  Input schema definition for the search_tasks tool, defining parameters like query, statuses, and assignees.

  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:23-57 (registration)

  Registration of the search_tasks handler in the _tools dictionary used by call_tool method.

  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 handler for listing tools, which returns definitions including search_tasks from ClickUpTools.

  @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:364-410 (helper)

  Underlying ClickUpClient method that performs the API search for tasks, called by the tool handler.

  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]