Todoist Python MCP Server

Instructions

Fetch user's tasks. These can be filtered by project, labels, time, etc. If no filters are provided, all tasks are returned.

Args:
- project_id: The string ID of the project to fetch tasks from. Example '1234567890'
- project_name: Name of the project to fetch tasks from. Example 'Work' or 'Inbox'
- task_name: Filter tasks by name. Example 'Buy groceries'
- labels: List of tags used to filter tasks.
- priority: Filter tasks by priority level. 4 (urgent), 3 (high), 2 (normal), 1 (low)
- due_date: Specific due date in YYYY-MM-DD format. Example '2021-12-31'
- is_overdue: Filter tasks that are overdue.
- limit: Maximum number of tasks to return. Default is all.

Implementation Reference

• todoist_server.py:58-121 (handler)

  The handler function decorated with @mcp.tool(), which registers and implements the get_tasks tool. Fetches tasks from Todoist API and applies filters based on project, name, labels, due date, overdue status, priority, and limit.

  @mcp.tool()
  def get_tasks(
      project_id: Optional[str] = None,
      project_name: Optional[str] = None,
      task_name: Optional[str] = None,
      labels: Optional[list[str]] = None,
      due_date: Optional[str] = None,
      is_overdue: Optional[bool] = None,
      priority: Optional[Literal[1, 2, 3, 4]] = None,
      limit: Optional[int] = None,
  ) -> list[str]:
      """
      Fetch user's tasks. These can be filtered by project, labels, time, etc. If no filters are provided, all tasks are returned.
  
      Args:
      - project_id: The string ID of the project to fetch tasks from. Example '1234567890'
      - project_name: Name of the project to fetch tasks from. Example 'Work' or 'Inbox'
      - task_name: Filter tasks by name. Example 'Buy groceries'
      - labels: List of tags used to filter tasks.
      - priority: Filter tasks by priority level. 4 (urgent), 3 (high), 2 (normal), 1 (low)
      - due_date: Specific due date in YYYY-MM-DD format. Example '2021-12-31'
      - is_overdue: Filter tasks that are overdue.
      - limit: Maximum number of tasks to return. Default is all.
      """
      tasks = todoist_api.get_tasks()
  
      # How to implement "did you mean this project?" feature?
      if project_name:
          project_id = get_project_id_by_name(project_name)
          if not project_id:
              raise ValueError(f"Project '{project_name}' not found")
  
      if project_id:
          project_id = project_id.strip('"')
          tasks = [t for t in tasks if t.project_id == project_id]
  
      if task_name:
          tasks = [t for t in tasks if task_name.lower() in t.content.lower()]
  
      if due_date:
          tasks = [t for t in tasks if t.due and t.due["date"] == due_date]
  
      if is_overdue is not None:
          now = datetime.today().strftime("%Y-%m-%d")
          tasks = [
              t for t in tasks if t.due and (date_difference(now, t.due["date"]) < 0) == is_overdue
          ]
  
      if labels:
          for label in labels:
              tasks = [t for t in tasks if label.lower() in [l.lower() for l in t.labels]]
  
      if priority:
          tasks = [t for t in tasks if t.priority == priority]
  
      return [
          {
              "id": t.id,
              "title": t.content,
              "priority": t.priority,
              "due": t.due["date"] if t.due else None,
          }
          for t in tasks
      ][:limit]

• todoist_server.py:58-58 (registration)

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

  @mcp.tool()

• todoist_server.py:59-81 (schema)

  Function signature with type annotations and detailed docstring defining the input schema and parameters for the get_tasks tool.

  def get_tasks(
      project_id: Optional[str] = None,
      project_name: Optional[str] = None,
      task_name: Optional[str] = None,
      labels: Optional[list[str]] = None,
      due_date: Optional[str] = None,
      is_overdue: Optional[bool] = None,
      priority: Optional[Literal[1, 2, 3, 4]] = None,
      limit: Optional[int] = None,
  ) -> list[str]:
      """
      Fetch user's tasks. These can be filtered by project, labels, time, etc. If no filters are provided, all tasks are returned.
  
      Args:
      - project_id: The string ID of the project to fetch tasks from. Example '1234567890'
      - project_name: Name of the project to fetch tasks from. Example 'Work' or 'Inbox'
      - task_name: Filter tasks by name. Example 'Buy groceries'
      - labels: List of tags used to filter tasks.
      - priority: Filter tasks by priority level. 4 (urgent), 3 (high), 2 (normal), 1 (low)
      - due_date: Specific due date in YYYY-MM-DD format. Example '2021-12-31'
      - is_overdue: Filter tasks that are overdue.
      - limit: Maximum number of tasks to return. Default is all.
      """

• todoist_server.py:49-56 (helper)

  Helper function used by get_tasks to resolve project_name to project_id.

  def get_project_id_by_name(project_name: str) -> str:
      """Search for a project by name and return its ID"""
      projects = get_projects()
      for project in projects:
          if project.name.lower() == project_name.lower():
              return project.id
      return None