API Documentation - Things Cloud MCP

Documentation

Complete reference for all 23 tools available through the Things Cloud MCP server.

Read

10 tools

things_find_tasks

List tasks with optional filters. Default pending results exclude descendants of completed, canceled, or trashed containers to match Things app visibility.

Parameter	Type	Description
schedule	enum	inbox, today, tonight, anytime, someday, upcoming
scheduled_before	string	YYYY-MM-DD
scheduled_after	string	YYYY-MM-DD
deadline_before	string	YYYY-MM-DD
deadline_after	string	YYYY-MM-DD
created_before	string	YYYY-MM-DD or RFC3339 with timezone
created_after	string	YYYY-MM-DD or RFC3339 with timezone
tag	string	Filter by tag
area	string	Filter by area
project	string	Filter by project
contains_text	string	Filter by text in title or note
in_trash	bool	Include trashed items (default false)
status	enum	pending (default), completed, canceled

things_show_task

Show task details including checklist. Accepts UUID prefix.

Parameter	Type	Description
uuidrequired	string	Task UUID or prefix

things_show_project

Show project with headings and grouped tasks

Parameter	Type	Description
uuidrequired	string	Project UUID
status	enum	Filter child tasks: pending (default), completed, canceled

things_find_projects

List projects with optional filters

Parameter	Type	Description
schedule	enum	inbox, today, tonight, anytime, someday, upcoming
scheduled_before	string	YYYY-MM-DD
scheduled_after	string	YYYY-MM-DD
deadline_before	string	YYYY-MM-DD
deadline_after	string	YYYY-MM-DD
created_before	string	YYYY-MM-DD or RFC3339 with timezone
created_after	string	YYYY-MM-DD or RFC3339 with timezone
tag	string	Filter by tag
area	string	Filter by area
contains_text	string	Filter by text in title or note
in_trash	bool	Include trashed items (default false)
status	enum	pending (default), completed, canceled

things_find_headings

List headings in a project

Parameter	Type	Description
project_uuidrequired	string	Project UUID

things_find_areas

List all areas

No parameters

things_find_tags

List all tags

No parameters

things_overview

Comprehensive active snapshot: tags, active area→project hierarchy, today's items (tasks & projects), and upcoming items. Descendants of inactive containers are excluded. Each item has a type field.

Parameter	Type	Description
lookahead_days	number	Days ahead to scan for upcoming items (default: 7)

things_debug_raw

Show all raw wire-format fields of a task or project. Accepts a UUID prefix.

Parameter	Type	Description
uuidrequired	string	Task or project UUID, or unique prefix

things_diagnose

Run a read-only diagnostic against the account's authoritative history and fail-closed sync pipeline

No parameters

Create

5 tools

things_create_task

Create a task

Parameter	Type	Description
titlerequired	string	Task title
note	string	Task notes
schedule	string	today, tonight, anytime, someday, inbox, or YYYY-MM-DD (Upcoming, auto-moves to Today when due)
deadline	string	YYYY-MM-DD
project_uuid	string	Assign to an active pending project; inactive projects are rejected
heading_uuid	string	Assign to an active heading in an active pending project
area_uuid	string	Assign to area
tags	string	Comma-separated tag UUIDs
checklist	string	Comma-separated checklist items
reminder_date	string	YYYY-MM-DD (use with reminder_time)
reminder_time	string	HH:MM 24h (use with reminder_date)
recurrence	string	daily, weekly, weekly:mon,wed, monthly, monthly:15, monthly:last, yearly, every N days/weeks

things_create_project

Create a project

Parameter	Type	Description
titlerequired	string	Project title
note	string	Project notes
schedule	string	today, anytime (default), someday, or YYYY-MM-DD
deadline	string	YYYY-MM-DD
area_uuid	string	Assign to area
tags	string	Comma-separated tag UUIDs
reminder_date	string	YYYY-MM-DD (use with reminder_time)
reminder_time	string	HH:MM 24h (use with reminder_date)
recurrence	string	daily, weekly, weekly:mon,wed, monthly, monthly:15, monthly:last, yearly, every N days/weeks

things_create_heading

Create a heading in a project

Parameter	Type	Description
titlerequired	string	Heading title
project_uuidrequired	string	Active pending parent project UUID; inactive projects are rejected

things_create_area

Create an area

Parameter	Type	Description
namerequired	string	Area name

things_create_tag

Create a tag

Parameter	Type	Description
namerequired	string	Tag name
shorthand	string	Short name for the tag
parent_uuid	string	Parent tag UUID for nesting

Modify

5 tools

things_edit_item

Edit a task or project (only provided fields change). Completing a recurring task completes only the current instance; stopping recurrence requires explicit confirmation.

Parameter	Type	Description
uuidrequired	string	Item UUID
title	string	New title
note	string	New notes; empty string clears them
schedule	string	today, tonight, anytime, someday, inbox, or YYYY-MM-DD (Upcoming, auto-moves to Today when due)
deadline	string	YYYY-MM-DD, or "none" to clear
area_uuid	string	Move to area
project_uuid	string	Move to an active pending project; inactive projects are rejected
heading_uuid	string	Move to an active heading in an active pending project
tags	string	Comma-separated tag UUIDs; empty string clears them
reminder_date	string	YYYY-MM-DD, or "none" to clear (use with reminder_time)
reminder_time	string	HH:MM 24h (use with reminder_date)
recurrence	string	daily, weekly, monthly, yearly, etc. Use "none" to clear.
confirm_destructive	bool	Must be true when recurrence is "none"
status	enum	pending, completed, canceled, trashed, restored

things_edit_area

Rename an area

Parameter	Type	Description
uuidrequired	string	Area UUID
namerequired	string	New area name

things_edit_tag

Edit a tag (name, shorthand, or parent)

Parameter	Type	Description
uuidrequired	string	Tag UUID
name	string	New tag name
shorthand	string	New shorthand/abbreviation
parent_uuid	string	New parent tag UUID

things_delete_area

Permanently delete an area

Parameter	Type	Description
uuidrequired	string	Area UUID
confirmrequired	bool	Must be true to confirm permanent deletion

things_delete_tag

Permanently delete a tag

Parameter	Type	Description
uuidrequired	string	Tag UUID
confirmrequired	bool	Must be true to confirm permanent deletion

Checklist

3 tools

things_add_checklist_item

Add a checklist item to a task

Parameter	Type	Description
task_uuidrequired	string	Parent task UUID
titlerequired	string	Checklist item title
index	number	Sort position (default 0)

things_edit_checklist_item

Edit a checklist item (only provided fields change)

Parameter	Type	Description
uuidrequired	string	Checklist item UUID
title	string	New title
index	number	New sort position
completed	bool	Set true to complete, false to mark pending

things_delete_checklist_item

Delete a checklist item

Parameter	Type	Description
uuidrequired	string	Checklist item UUID
confirmrequired	bool	Must be true to confirm permanent deletion

Output Format

All 23 tools declare an MCP outputSchema. Successful calls return schema-validated structuredContent in a stable data envelope, plus an equivalent JSON text fallback for older clients:

{
  "data": {
    "uuid": "...",
    "title": "...",
    "note": "...",
    "status": "pending | completed | canceled",
    "schedule": "inbox | today | tonight | anytime | someday | upcoming",
    "scheduledDate": "YYYY-MM-DD",
    "deadlineDate": "YYYY-MM-DD",
    "creationDate": "YYYY-MM-DDTHH:MM:SSZ",
    "modificationDate": "YYYY-MM-DDTHH:MM:SSZ",
    "completionDate": "YYYY-MM-DDTHH:MM:SSZ",
    "areas": [{"uuid": "...", "name": "..."}],
    "project": {"uuid": "...", "name": "..."},
    "tags": [{"uuid": "...", "name": "..."}]
  }
}

Setup MCP with ChatGPT ▾

Open Customize → Connectors in Claude.

Click +, then choose Add custom connector.

Enter name: Things Cloud and URL: .

Click Add, then Connect and complete the Things Cloud sign-in. Enable it in a chat from + → Connectors.

View Claude’s official instructions ↗

Open Settings → Security and login and enable Developer mode.

Open Plugins from the sidebar and click Create app.

Use name: Things Cloud, connection: Server URL, URL: , and authentication: OAuth.

Acknowledge the unreviewed-server warning, click Create, and complete the Things Cloud sign-in.

Use these standard connection details in any MCP client that supports remote Streamable HTTP.

Server URL

TransportStreamable HTTP

AuthenticationOAuth 2.1 + PKCE

RegistrationDCR

Basic authentication remains available for legacy clients, but OAuth is recommended.