MCP Tools: List Items

Last updated About 4 hours ago

MCP Tools: List Items ​

Tasks ("items") live inside lists. Assignments are stored in refs ({type:'user',id}) and are returned as assignees.

list_list_items ​

Filter items. read · follower

ParameterTypeDefaultDescription
listIdstring–Filter by list
stateenum open | done | allallopen = not completed (status not done/completed)
statusstring–Exact status (e.g. todo). For "not finished", prefer state
prioritynumber (1–9)–Filter by priority
assigned_tostring–Filter by assigned user (refs, type=user)
assigned_to_meboolean–Only items assigned to me (no get_me needed)
tagstring–Exact tag (e.g. ki/claude)
searchstring–Search in text and description
due_within_daysnumber–Due within N days (including overdue)
due_beforestring (ISO)–Due before a date
includeArchivedbooleanfalseInclude archived items
sortenum default | priority | due_date | created | modifieddefaultSort order
compactbooleanfalseCore fields + assignees only
limitnumber50Count
offsetnumber0Skip

Response: { items, total, limit, offset, has_more }.

get_list_item ​

A single item. read · follower

ParameterTypeDescription
itemIdstring (required)UUID or SID

create_list_item ​

Create a new item. write · user

ParameterTypeDescription
listIdstring (required)UUID or SID of the list
textstring (required)Title (min. 1 character)
descriptionstringDescription
statusstringStatus
prioritynumber (1–9)Priority (9 = urgent)
assigned_tostring[]Assigned user IDs
tagsstring[]Tags
target_datestring (ISO)Due date
parentstringParent item
typestringType (free-form, e.g. a box-type key for info-column boxes)
anchorstringItem this item docks onto (info-/detail-column mechanism). Set together with parent when the item should also be a structural child of it — anchor only drives the display layer, parent remains the source of truth for the overall tree.
layernumber ≥ 0Display layer for the anchor mechanism (0 = main list). Only meaningful together with anchor.
contentobject | array | stringStructured content payload (e.g. box-type-specific data). Objects/arrays are stored as JSON.

update_list_item ​

Update an item. write · user

ParameterTypeDescription
itemIdstring (required)UUID or SID
text, description, statusstringnew values
prioritynumber (1–9)new priority
assigned_tostring[]new assignments
tagsstring[]new tags
target_datestring | nullnew date
progressnumber (0–100)Progress
archivedbooleanarchive
typestringnew type
anchorstring | nullnew anchor item (or null to clear)
layernumber | nullnew display layer (or null to clear)
contentobject | array | stringnew structured content payload
expectedVersionintegerOptimistic Lock

complete_list_item ​

Mark as completed (status done, progress 100). write · user

ParameterTypeDefaultDescription
itemIdstring (required)–UUID or SID
reopenbooleanfalseReopen (status open, progress 0)
expectedVersioninteger–Optimistic Lock

complete_list_items ​

Complete/reopen multiple items (bulk). write · user

ParameterTypeDefaultDescription
itemIdsstring[] (required)–UUIDs/SIDs (min. 1)
reopenbooleanfalseReopen instead of completing

Response: { succeeded, failed, results[] } (per-item result).

update_list_items ​

Apply the same field updates to multiple items (bulk). write · user

ParameterTypeDescription
itemIdsstring[] (required)UUIDs/SIDs (min. 1)
statusstringfor all
prioritynumber (1–9)for all
assigned_tostring[]for all
tagsstring[]for all
target_datestring | nullfor all
progressnumber (0–100)for all
archivedbooleanfor all

delete_list_item ​

Move to the trash. destructive · admin

ParameterTypeDescription
itemIdstring (required)UUID or SID
expectedVersionintegerOptimistic Lock

get_overdue_list_items ​

Overdue items. read · follower

ParameterTypeDefaultDescription
listIdstring–By list
compactbooleanfalseCore fields + days_overdue
limitnumber50Count

get_my_open_items ​

My open tasks (overdue → due → priority). read · follower

ParameterTypeDefaultDescription
listIdstring–Restrict to a single list
includeUndatedbooleantrueInclude items without a date
compactbooleanfalseCore fields
limitnumber50Count

list_recent_changes ​

Recently changed items (sync/polling). read · follower

ParameterTypeDefaultDescription
sincestring (ISO)–Only items changed since this point in time
listIdstring–Restrict to a single list
compactbooleanfalseCore fields + modified
limitnumber50Count

search_list_items ​

Full-text search across items. read · follower

ParameterTypeDefaultDescription
querystring (required)–Search term (min. 1 character)
compactbooleanfalseCore fields
limitnumber20Count

post_chat_message ​

Post a message to an item's chat (or a list's chat). write · user

ParameterTypeDescription
itemIdstringTarget item (UUID/SID)
listIdstringTarget list (alternative to itemId)
textstring (required)Message text

get_chat_messages ​

Read the chat history (oldest first). read · follower

ParameterTypeDefaultDescription
itemIdstring–Item chat
listIdstring–List chat (alternative)
limitnumber50Max. messages
offsetnumber0Skip

get_metadata ​

Reference: valid status/priority/scope/filter values. read · guest

No parameters. Call before creating/updating to use correct values.