Todoist MCP Server

Instructions

Implementation Reference

• todoist_mcp/server.py:37-75 (handler)

  The primary MCP tool handler for 'get_tasks'. It accepts filtering parameters, calls the TodoistClient's get_tasks method, formats the results into a human-readable string list, and returns it.
  @mcp.tool() async def get_tasks( project_id: Optional[str] = None, section_id: Optional[str] = None, label: Optional[str] = None, filter_query: Optional[str] = None ) -> str: """Get tasks from Todoist with optional filtering. Args: project_id: Filter tasks by project ID section_id: Filter tasks by section ID label: Filter tasks by label filter_query: Natural language filter (e.g., 'today', 'overdue', 'p1') """ _check_client() tasks = await todoist_client.get_tasks( project_id=project_id, section_id=section_id, label=label, filter_query=filter_query ) if not tasks: return "No tasks found." task_list = [] for task in tasks: task_info = f"• [{task.id}] {task.content}" if task.due_string or task.due_date: task_info += f" (Due: {task.due_string or task.due_date})" if task.priority > 1: task_info += f" [Priority: {task.priority}]" if task.labels: task_info += f" Labels: {', '.join(task.labels)}" task_list.append(task_info) return f"Found {len(tasks)} tasks:\n" + "\n".join(task_list)
• todoist_mcp/client.py:77-94 (helper)

  Helper method in TodoistClient class that performs the actual API request to fetch tasks from Todoist with optional filters and parses into TodoistTask models.
  async def get_tasks(self, project_id: Optional[str] = None, section_id: Optional[str] = None, label: Optional[str] = None, filter_query: Optional[str] = None) -> List[TodoistTask]: """Get tasks with optional filtering.""" params = {} if project_id: params["project_id"] = project_id if section_id: params["section_id"] = section_id if label: params["label"] = label if filter_query: params["filter"] = filter_query data = await self._request("GET", "/tasks", params=params) return [TodoistTask(**task) for task in data]
• todoist_mcp/client.py:9-25 (schema)

  Pydantic BaseModel schema for TodoistTask, used to validate and structure task data returned from the Todoist API in get_tasks.
  class TodoistTask(BaseModel): """Represents a Todoist task.""" id: str content: str description: str = "" is_completed: bool = False labels: List[str] = [] priority: int = 1 due_string: Optional[str] = None due_date: Optional[str] = None project_id: str = "" section_id: Optional[str] = None parent_id: Optional[str] = None order: int = 0 url: str = "" created_at: str = ""
• todoist_mcp/server.py:37-37 (registration)

  The @mcp.tool() decorator registers the get_tasks function as an MCP tool.
  @mcp.tool()