Todoist MCP Server

Instructions

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')

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()