get_tasks
Fetch user tasks from Todoist with filtering options for project, labels, priority, due date, and more. Returns tasks matching specified criteria or all tasks if no filters are applied.
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| due_date | No | ||
| is_overdue | No | ||
| labels | No | ||
| limit | No | ||
| priority | No | ||
| project_id | No | ||
| project_name | No | ||
| task_name | No |
Input Schema (JSON Schema)
{
"properties": {
"due_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Due Date"
},
"is_overdue": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Is Overdue"
},
"labels": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Labels"
},
"limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Limit"
},
"priority": {
"anyOf": [
{
"enum": [
1,
2,
3,
4
],
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Priority"
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Project Id"
},
"project_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Project Name"
},
"task_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Task Name"
}
},
"title": "get_tasksArguments",
"type": "object"
}
Implementation Reference
- todoist_server.py:58-121 (handler)The handler function for the 'get_tasks' tool. Decorated with @mcp.tool(), which registers the tool and infers schema from function signature and docstring. Implements filtering logic for tasks based on various parameters using Todoist API.@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]