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

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 snapshot: tags, area→project hierarchy, today's items (tasks & projects), upcoming items. 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

uuid required

things_diagnose

Run full diagnostic of the Things Cloud 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 project
heading_uuid	string	Assign to heading within 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	Parent project UUID

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.

Parameter	Type	Description
uuidrequired	string	Item UUID
title	string	New title
note	string	New notes
schedule	string	today, tonight, anytime, someday, inbox, or YYYY-MM-DD (Upcoming, auto-moves to Today when due)
deadline	string	YYYY-MM-DD
area_uuid	string	Move to area
project_uuid	string	Move to project
heading_uuid	string	Move to heading
tags	string	Comma-separated tag UUIDs
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.
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

things_delete_tag

Permanently delete a tag

Parameter	Type	Description
uuidrequired	string	Tag UUID

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

Output Format

Tasks are returned in the following JSON shape:

{
  "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": "..."}]
}

Get Started

Setup MCP with Claude.ai ▾

Go to Settings → Connectors → Add custom connector

Enter name: Things Cloud

Enter URL:

Click Add, then enable in chat via the “+” button

Run the following command:

claude mcp add --transport http \
  things-cloud  \
  --header "Authorization: Basic BASE64_ENCODE(email:password)"

Replace BASE64_ENCODE(email:password) with your base64-encoded Things Cloud credentials (email:password). Generate with: echo -n 'email:password' | base64

Verify with the /mcp command inside Claude Code.

Go to Settings → Apps & Connectors → Advanced, enable Developer Mode

Click Add Connector

Enter name: Things Cloud, URL:

In a new chat, click “+” to select the connector

Note: ChatGPT requires a publicly accessible URL (use ngrok for local dev).

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "things-cloud": {
      "url": "",
      "headers": {
        "Authorization": "Basic BASE64_ENCODE(email:password)"
      }
    }
  }
}

Replace BASE64_ENCODE(email:password) with your base64-encoded Things Cloud credentials (email:password). Generate with: echo -n 'email:password' | base64

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "things-cloud": {
      "serverUrl": "",
      "headers": {
        "Authorization": "Basic BASE64_ENCODE(email:password)"
      }
    }
  }
}

Replace BASE64_ENCODE(email:password) with your base64-encoded Things Cloud credentials (email:password). Generate with: echo -n 'email:password' | base64