ClickUp MCP Server

Instructions

Implementation Reference

• src/clickup_mcp/tools.py:625-668 (handler)

  Main MCP tool handler for 'get_task'. Resolves task ID using helper, fetches details via client, formats response with task info, assignees, dates, etc.
  async def get_task( self, task_id: str, include_subtasks: bool = False, ) -> Dict[str, Any]: """Get task details.""" try: task = await self._resolve_task_id(task_id, include_subtasks) except ClickUpAPIError as e: return {"error": f"Failed to get task '{task_id}': {e!s}"} result = { "id": task.id, "name": task.name, "description": task.description or "", "status": task.status.status, "priority": task.priority.value if task.priority else None, "assignees": [{"id": u.id, "username": u.username} for u in task.assignees], "creator": {"id": task.creator.id, "username": task.creator.username}, "list": task.list.get("name", "Unknown"), "space": task.space.get("name", "Unknown"), "url": format_task_url(task.id), "tags": task.tags, } if task.custom_id: result["custom_id"] = task.custom_id if task.due_date: result["due_date"] = task.due_date.isoformat() if task.time_estimate: result["time_estimate"] = task.time_estimate // 1000 // 60 # Convert to minutes if task.time_spent: result["time_spent"] = task.time_spent // 1000 // 60 # Convert to minutes if include_subtasks and task.parent: # Fetch subtasks subtasks = await self.get_subtasks(task.parent) result["subtasks"] = subtasks return result
• src/clickup_mcp/tools.py:97-113 (schema)

  Input schema definition for the 'get_task' tool, specifying task_id as required and include_subtasks optional.
  name="get_task", description="Get task details by ID (supports various ID formats including project codes)", inputSchema={ "type": "object", "properties": { "task_id": { "type": "string", "description": "Task ID, custom ID (e.g., gh-123), or URL", }, "include_subtasks": { "type": "boolean", "description": "Include subtasks in response", }, }, "required": ["task_id"], }, ),
• src/clickup_mcp/tools.py:23-57 (registration)

  Registration of 'get_task' 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/tools.py:527-567 (helper)

  Helper function to resolve flexible task IDs (internal, custom like gh-123, search fallback) before calling client API.
  async def _resolve_task_id(self, task_id: str, include_subtasks: bool = False) -> Task: """Smart task ID resolution that handles both internal and custom IDs.""" # Parse task ID to determine if it might be a custom ID parsed_id, custom_type = parse_task_id(task_id, self.client.config.id_patterns) # Try direct lookup first (works for both internal and custom IDs) try: return await self.client.get_task(parsed_id, include_subtasks=include_subtasks) except ClickUpAPIError as direct_error: # If it might be a custom ID, try with custom_task_ids=true if custom_type or "-" in parsed_id: try: team_id = ( self.client.config.default_team_id or self.client.config.default_workspace_id ) return await self.client.get_task( parsed_id, include_subtasks=include_subtasks, custom_task_ids=True, team_id=team_id, ) except ClickUpAPIError as custom_error: # If both fail, try search as final fallback try: tasks = await self.client.search_tasks(query=task_id) if not tasks: raise ClickUpAPIError(f"Task '{task_id}' not found") # Find exact match by custom_id or use first result for task in tasks: if hasattr(task, "custom_id") and task.custom_id == task_id: return task return tasks[0] except ClickUpAPIError: # Re-raise the most relevant error raise (custom_error if custom_type else direct_error) from None else: # Not a custom ID pattern, re-raise the original error raise direct_error
• src/clickup_mcp/client.py:287-304 (helper)

  Low-level ClickUp API client method to fetch task by ID, supports subtasks and custom IDs, returns Task model.
  async def get_task( self, task_id: str, include_subtasks: bool = False, custom_task_ids: bool = False, team_id: Optional[str] = None, ) -> Task: """Get a task by ID.""" params = {} if include_subtasks: params["include_subtasks"] = "true" if custom_task_ids: params["custom_task_ids"] = "true" if team_id: params["team_id"] = team_id data = await self._request("GET", f"/task/{task_id}", params=params) return Task(**data)