Documentation

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

Read

7 tools

list_tasks

List tasks with optional filters

Parameter	Type	Description
schedule	enum	inbox, today, 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
tag	string	Filter by tag
area	string	Filter by area
project	string	Filter by project
in_trash	bool	Include trashed items (default false)
is_completed	bool	Include completed items (default false)

show_task

Show task details including checklist. Accepts UUID prefix.

Parameter	Type	Description
uuidrequired	string	Task UUID or prefix

show_project

Show project with headings and grouped tasks

Parameter	Type	Description
uuidrequired	string	Project UUID or prefix

list_projects

List all active projects

No parameters

list_headings

List headings in a project

Parameter	Type	Description
project_uuidrequired	string	Project UUID

list_areas

List all areas

No parameters

list_tags

List all tags

No parameters

Create

5 tools

create_task

Create a task

Parameter	Type	Description
titlerequired	string	Task title
note	string	Task notes
schedule	string	today, 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

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
recurrence	string	daily, weekly, weekly:mon,wed, monthly, monthly:15, monthly:last, yearly, every N days/weeks

create_heading

Create a heading in a project

Parameter	Type	Description
titlerequired	string	Heading title
project_uuidrequired	string	Parent project UUID

create_area

Create an area

Parameter	Type	Description
namerequired	string	Area name

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

7 tools

edit_item

Edit a task or project (only provided fields change)

Parameter	Type	Description
uuidrequired	string	Item UUID
title	string	New title
note	string	New notes
schedule	string	today, 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
recurrence	string	daily, weekly, monthly, yearly, etc. Use "none" to clear.
status	enum	pending, completed, canceled

edit_area

Rename an area

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

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

trash_item

Move an item to trash

Parameter	Type	Description
uuidrequired	string	Item UUID

restore_item

Restore an item from trash

Parameter	Type	Description
uuidrequired	string	Item UUID

delete_area

Permanently delete an area

Parameter	Type	Description
uuidrequired	string	Area UUID

delete_tag

Permanently delete a tag

Parameter	Type	Description
uuidrequired	string	Tag UUID

Checklist

4 tools

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)

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

complete_checklist_item

Complete or uncomplete a checklist item

Parameter	Type	Description
uuidrequired	string	Checklist item UUID
uncomplete	bool	Set true to mark as pending instead (default false)

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 | 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 \
  --header "Authorization: Basic BASE64_ENCODE(email:password)" \
  things-cloud

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