Todoist MCP Server

Instructions

Implementation Reference

• src/tasks.py:121-240 (handler)

  Main handler function implementing the todoist_get_tasks tool. Fetches tasks from Todoist API supporting filters by project, section, parent, label, or IDs, with pagination handling up to nmax tasks.
  def todoist_get_tasks( ctx: Context, project_id: Optional[str] = None, section_id: Optional[str] = None, parent_id: Optional[str] = None, label: Optional[str] = None, ids: Optional[list[str]] = None, nmax: Optional[int] = 100, limit: int = 200 ) -> str: """Get a list of tasks from Todoist with basic filters This is a wrapper around the Todoist API's get_tasks method that handles pagination automatically. By default, it will fetch up to 100 matching tasks. Set nmax=None to fetch ALL matching tasks across multiple API calls. For natural language filtering (like 'today', 'overdue'), use todoist_filter_tasks instead. Examples: # Get up to 100 tasks (default) todoist_get_tasks(ctx) # Get all tasks in a project (up to 100 by default) todoist_get_tasks(ctx, project_id="12345") # Get first 500 tasks total todoist_get_tasks(ctx, nmax=500) # Get ALL tasks (unlimited) todoist_get_tasks(ctx, nmax=None) # Get specific tasks by ID todoist_get_tasks(ctx, ids=["task1", "task2", "task3"]) Args: project_id: Filter tasks by project ID (optional) section_id: Filter tasks by section ID (optional) parent_id: Filter tasks by parent task ID (optional) label: Filter tasks by label name (optional) ids: A list of the IDs of the tasks to retrieve (optional) nmax: Maximum total number of tasks to return. Set to None for ALL matching tasks (default: 100) limit: Number of tasks to fetch per API request (default: 200, max: 200) """ todoist_client = ctx.request_context.lifespan_context.todoist_client try: logger.info(f"Getting tasks with project_id: {project_id}, section_id: {section_id}, parent_id: {parent_id}, label: {label}, nmax: {nmax}, limit: {limit}") # Early exit for zero requests to avoid unnecessary API calls if nmax is not None: if nmax == 0: logger.info("nmax=0 specified, returning empty result") return [] elif nmax < 0: logger.warning(f"Invalid nmax {nmax}, using default of 100") nmax = 100 if limit > 200: logger.warning(f"Limit {limit} exceeds API maximum of 200, using 200 instead") limit = 200 elif limit <= 0: logger.warning(f"Invalid limit {limit}, using default of 200") limit = 200 # Key optimization: match page size to actual need to reduce API payload effective_limit = limit if nmax is not None and nmax < limit: effective_limit = nmax logger.info(f"Optimized limit from {limit} to {effective_limit} to match nmax") params = {} if project_id: params["project_id"] = project_id if section_id: params["section_id"] = section_id if parent_id: params["parent_id"] = parent_id if label: params["label"] = label if ids: params["ids"] = ids params["limit"] = effective_limit tasks_iterator = todoist_client.get_tasks(**params) all_tasks = [] pages_fetched = 0 for task_batch in tasks_iterator: pages_fetched += 1 all_tasks.extend(task_batch) logger.info(f"Fetched page {pages_fetched} with {len(task_batch)} tasks (total: {len(all_tasks)})") if nmax is not None and len(all_tasks) >= nmax: # Trim excess - rare due to effective_limit optimization, but handles edge cases all_tasks = all_tasks[:nmax] logger.info(f"Reached nmax of {nmax} tasks, stopping pagination") break # Todoist API signals end of results by returning fewer items than requested if len(task_batch) < effective_limit: logger.info(f"Received {len(task_batch)} tasks (less than limit {effective_limit}), reached end of results") break if not all_tasks: logger.info("No tasks found matching the criteria") return "No tasks found matching the criteria" logger.info(f"Retrieved {len(all_tasks)} tasks total across {pages_fetched} pages") if nmax is None: logger.info("Fetched ALL matching tasks (nmax=None specified)") elif len(all_tasks) == nmax: logger.info(f"Retrieved exactly the requested {nmax} tasks") return json.dumps([task.to_dict() for task in all_tasks], indent=2, default=str) except Exception as error: logger.error(f"Error getting tasks: {error}") return f"Error getting tasks: {str(error)}"
• src/main.py:85-85 (registration)

  Registers the todoist_get_tasks handler as an MCP tool using FastMCP's decorator.
  mcp.tool()(todoist_get_tasks)
• src/main.py:26-36 (registration)

  Imports the todoist_get_tasks function from tasks module for registration.
  from .tasks import ( todoist_get_task, todoist_get_tasks, todoist_filter_tasks, todoist_add_task, todoist_update_task, todoist_complete_task, todoist_uncomplete_task, todoist_move_task, todoist_delete_task, )