List Tasks
vault_list_tasksList tasks across an Obsidian vault with structured filters for dates, status, priority, and folder — get overdue, open, or completed items with note paths and line numbers in one call.
Instructions
List checkbox tasks across the whole vault with structured filters — the Tasks-plugin data model over MCP. Both task metadata formats are indexed: emoji signifiers (📅 due, ⏳ scheduled, 🛫 start, ➕ created, ✅ done, ❌ cancelled, 🔺⏫🔼🔽⏬ priority, 🔁 recurrence, 🏁 onCompletion, 🆔/⛔ dependencies) and Dataview inline fields ([due:: 2026-07-04], [priority:: high], ...). Every result carries its attribution — note path, folder, line number, and the nearest heading when the task sits under one (the lane on a Kanban board) — so no follow-up reads are needed to locate a task. Task lines inside fenced code blocks and %% %% comment blocks are not indexed. Checkboxes typed NON_TASK in the Tasks plugin's status registry are also excluded.
Example: vault_list_tasks({ due: { before: "2026-07-04" } }) — overdue triage; the default status (not_done) and sort (due ascending) make this the "what's overdue?" call Example: vault_list_tasks({ path: "Code Projects/vault-cortex/TASKS.md", heading: ["Active", "Up Next", "Waiting On"], sort_by: "position" }) — actionable Kanban lanes in board order Example: vault_list_tasks({ folder: "Code Projects/vault-cortex" }) — all open tasks across a project tree (TASKS.md + task-notes/ subdirectories) Example: vault_list_tasks({ status: "done", done: { after: "2026-06-26" } }) — what got completed this week Example: vault_list_tasks({ top_level_only: true, path: "TASKS.md" }) — board cards only, excluding checklist sub-items
When to use: Reading task status and order on one board (path + sort_by: "position"; add status: "all" to include done and cancelled cards). Also any vault-wide task triage question — "what's overdue?", "what's open per project?", "what did I finish this week?" — in one call instead of per-board reads. Prefer vault_read_note (heading mode) only when you need a lane's verbatim Markdown or a task's state right after a write. Prefer vault_search for full-text queries over note content.
Behavior: Reads the search index, which picks up a file change within a few seconds, so a task written moments ago may still show its old state.
Parameters:
status: virtual values expand in arrays — ["not_done", "done"] matches todo + in_progress + done.
due / scheduled / start / done / created / cancelled: a date filter only matches tasks that HAVE that date.
folder: a whole folder, subfolders included ("Projects" covers "Projects/Archive" but not "ProjectsOld/"), ignoring ASCII letter case.
Errors:
A malformed or calendar-invalid date filter throws with remediation text ("Use YYYY-MM-DD")
path without the ".md" extension is rejected
No matches returns { total: 0, tasks: [] }, not an error
Returns: JSON { total, tasks }. Every task carries path, line, status, status_char, description, folder, depth (0 for top-level, 1+ for sub-tasks), is_kanban_task, depends_on, and tags (the arrays are [] when empty). Every other field appears only when the task has it: heading (nearest heading above the task), created/scheduled/start/due/done/cancelled dates, priority, recurrence, on_completion, task_id, block_id, parent_block_id (sub-tasks whose parent carries a ^block-id), done_lanes (Kanban boards only), and subtask_progress — { done, total } over the task's DIRECT checklist children, present only when the task has a checklist; done counts status "done" only (a cancelled child counts toward total, not done), and the counts ignore the query's filters — so a filtered or top_level_only read still shows each card's checklist progress.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| due | No | Due date (📅 / [due:: ]) bounds | |
| tag | No | Inline task tag, bare name without "#"; parent tags match children | |
| done | No | Done date (✅ / [completion:: ]) bounds | |
| path | No | Restrict to one note (vault-relative path ending ".md", case-sensitive) | |
| limit | No | Max results (default 50); total always reports the full match count | |
| start | No | Start date (🛫 / [start:: ]) bounds | |
| folder | No | Restrict to a folder (e.g. "Code Projects/vault-cortex") | |
| status | No | Status filter, OR-combined (default "not_done" = todo + in_progress, excluding done and cancelled). "all" includes every status. | not_done |
| created | No | Created date (➕ / [created:: ]) bounds | |
| heading | No | Exact heading text or array of headings, OR-combined, case-sensitive (e.g. "Active" or ["Active", "Up Next"]) | |
| sort_by | No | Sort key (default "due"). Date sorts cascade through related fields when the primary is absent (through the rest of due → scheduled → start → created, in that order; done does not cascade); each fallback uses its own natural direction. "position" sorts by file path then line number — the natural order for Kanban boards. | due |
| priority | No | Priority levels, OR-combined; "none" selects tasks with no priority signifier | |
| cancelled | No | Cancelled date (❌ / [cancelled:: ]) bounds | |
| scheduled | No | Scheduled date (⏳ / [scheduled:: ]) bounds | |
| sort_direction | No | Sort direction. Default per field: "asc" for due/scheduled/priority/position, "desc" for start/created/done/note_mtime. Within a date cascade, each fallback uses its own default; an explicit value overrides all fields uniformly. | |
| top_level_only | No | When true, only top-level tasks (depth 0) are returned — excludes indented sub-tasks and checklist items. Default false. |