Todoist Python MCP Server

Instructions

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