ClickUp MCP Server

Instructions

Implementation Reference

• src/clickup_mcp/tools.py:1385-1419 (handler)

  The main handler function implementing the find_user_by_name tool. It fetches workspace members via the client and searches for matches by name or email (case-insensitive).

  async def find_user_by_name(
      self, name: str, workspace_id: Optional[str] = None
  ) -> Dict[str, Any]:
      """Find a user by name or email."""
      members = await self.client.get_workspace_members(workspace_id)
  
      # Search by username or email (case-insensitive)
      name_lower = name.lower()
      matches = []
  
      for member in members:
          username = member.get("username", "").lower()
          email = member.get("email", "").lower()
  
          if name_lower in username or name_lower in email:
              matches.append(
                  {
                      "id": member.get("id"),
                      "username": member.get("username"),
                      "email": member.get("email"),
                      "initials": member.get("initials"),
                      "color": member.get("color"),
                      "profilePicture": member.get("profilePicture"),
                  }
              )
  
      if not matches:
          return {"error": f"No user found matching '{name}'", "matches": []}
  
      return {
          "matches": matches,
          "count": len(matches),
          "found": True,
      }

• src/clickup_mcp/tools.py:490-507 (schema)

  The input schema and description for the find_user_by_name tool defined in get_tool_definitions().

  Tool(
      name="find_user_by_name",
      description="Find a user by name or email",
      inputSchema={
          "type": "object",
          "properties": {
              "name": {
                  "type": "string",
                  "description": "Name or email to search for",
              },
              "workspace_id": {
                  "type": "string",
                  "description": "Workspace ID (optional, uses default if not provided)",
              },
          },
          "required": ["name"],
      },
  ),

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

  Registration of the find_user_by_name handler in the ClickUpTools class's _tools dictionary during __init__.

  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 point where list_tools handler returns tool definitions including find_user_by_name.

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