things_add_items_to_project
Add todos and headings to an existing project. Items are added as a flat array where headings act as visual separators for the todos that follow them.
LABSCO SUMMARY
Project scaffolding in one call, not a stream of separate task creations
things_add_project takes an items array in which headings act as dividers for the to-dos beneath them, so a plan with phases lands structured instead of as a flat pile that you then reorganise by hand. Reading is equally complete — every built-in list has its own tool and its own max_results ceiling, which keeps a Logbook query from dragging in years of history. Updates route through the JSON API path, and that is where completed and canceled state is set rather than through a separate action.
What it is
A Things client with 20 tools that write to-dos and projects into the app and read every built-in list, area and tag back out.
What you get
- To-do creation carrying title, notes, tags, deadline, when, target list and checklist_items for tasks with several components
- Project creation where the items array mixes to-dos and headings, and each heading groups the to-dos that follow it
- A dedicated read for each built-in list — Inbox, Today, Upcoming, Anytime, Someday, Logbook and Trash — each bounded by max_results
- Reads by container: a specific project, an area, or a list by name, plus areas, tags and active projects in full
- Deadline, notes and status for a single to-do through things_get_todo_details
- Updates to an existing to-do or project, including completed and canceled state, and appending items to a project already in flight
- Navigation that opens a specific item, list or search inside the app
Requirements
Things itself plus its authorization token in THINGS_AUTH_TOKEN; every read and write in the tool set goes through the app.
Setup effort
One command plus a key — npx github:hildersantos/things-mcp, then supply credentials
USE CASES
01
Turning a planning conversation into a project with phases
The plan arrives as one project whose headings separate the phases, and later additions drop into the same structure rather than at the bottom of a flat list.
02
Clearing the inbox before the week starts
Everything captured in a hurry is read back in one call, sorted into lists or dated, and the item that needs a human decision is opened in the app.
03
Working out what is genuinely due today
Today's list on its own hides what is about to land. Reading the scheduled items alongside it turns an optimistic day into a realistic one.
04
Reconstructing what actually shipped last month
The Logbook holds completed work with its dates and notes, which is the raw material for a status report you would otherwise write from memory.
05
Filing a task with its subtasks in one go
A task that has several components lands as a single to-do carrying its checklist, rather than as a project you did not want or five loose items.
06
Auditing an area that has quietly grown
Areas accumulate projects and tags nobody reviews. Reading the area's contents next to the active project list shows what has stalled.
20 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
things_add_project
Creates a project in Things with support for sections (headings) and todos. Perfect for complex projects with multiple phases, days, or categories. Headings act as visual dividers - todos that follow a heading in the items array will appear grouped under it.
things_add_todo
Add a new to-do to Things with full support for checklists to break down complex tasks into manageable steps. Use checklist when task has multiple components that don't warrant a separate project.
things_get_anytime
Get all to-dos in Anytime
things_get_area
Get all items in a specific area
things_get_areas
Get all areas
things_get_inbox
Get all to-dos in the Inbox
things_get_list
Get all to-dos from a specific list by name
things_get_logbook
Get all completed to-dos in the Logbook
things_get_project
Get all to-dos in a specific project
things_get_projects
Get all active projects
things_get_someday
Get all to-dos in Someday
things_get_tags
Get all tags
things_get_today
Get all to-dos scheduled for Today
things_get_todo_details
Get detailed information about a specific to-do including deadline, notes, status, etc.
things_get_trash
Get all deleted to-dos in the Trash
things_get_upcoming
Get all scheduled to-dos (with dates)
things_show
Navigate to a specific item or list in Things
things_update_project
Update an existing project in Things using JSON API for full feature support
things_update_todo
Update an existing to-do in Things using JSON API for full feature support
BEFORE YOU INSTALL
What to know first
Tools you get
20 tools when we connected. The update tools need THINGS_AUTH_TOKEN; without it you can create and read but not change existing items. There is no search tool.
Requires
- npx on PATH
- Node.js 18 or later
- THINGS_AUTH_TOKEN in your environment
CONTEXT COST
Light Standing cost
Rated by the size of the 20 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx github:hildersantos/things-mcpMCP Clients
Claude Desktop — npx
CLAUDE DESKTOP — NPX · JSON
{
"mcpServers": {
"things-mcp": {
"command": "npx",
"args": [
"github:hildersantos/things-mcp"
],
"env": {
"THINGS_AUTH_TOKEN": "<YOUR_THINGS_AUTH_TOKEN>"
}
}
}
}Claude Desktop — local install
CLAUDE DESKTOP — LOCAL INSTALL · TERMINAL
git clone https://github.com/hildersantos/things-mcp.git
cd things-mcp
npm install
npm run buildAdd the server to Claude Desktop with the full path to dist/index.js in that folder
CLAUDE DESKTOP — LOCAL INSTALL · JSON
{
"mcpServers": {
"things-mcp": {
"command": "node",
"args": [
"<YOUR_PATH_TO_THINGS_MCP>/dist/index.js"
],
"env": {
"THINGS_AUTH_TOKEN": "<YOUR_THINGS_AUTH_TOKEN>"
}
}
}
}<YOUR_PATH_TO_THINGS_MCP> is the full path of your clone, and <YOUR_THINGS_AUTH_TOKEN> is your Things auth token (Things → Settings → General → Enable Things URLs → Manage → Copy Token).
