Skip to content
Back to search

things-mcp

Things.app MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hald--things-mcp/badge.svg)](/listings/hald--things-mcp)

HTML

<a href="/listings/hald--things-mcp"><img src="/api/listings/hald--things-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- macOS (Things 3 is Mac-only) - Things 3 app with "Enable Things URLs" turned on (Settings → General) - A MCP client, such as Claude Desktop or Claude Code - [uv](https://docs.astral.sh/uv/) Python package manager: `brew install uv`

Install via uvx (Any MCP Client)

Things MCP is published on PyPI and can be run directly with `uvx`:

uvx things-mcp

Configure your MCP client to use `uvx` with `things-mcp` as the argument.

Claude Desktop

Option 1: One-Click Install (Recommended)

1. Download the latest file from the [releases page](https://github.com/hald/things-mcp/releases) 2. Double-click the `.mcpb` file 3. Done!

Option 2: Manual Config

1. Go to **Claude → Settings → Developer → Edit Config** 2. Add the Things server:

{
  "mcpServers": {
    "things": {
      "command": "uvx",
      "args": ["things-mcp"]
    }
  }
}

3. Save and restart Claude Desktop

Claude Code

claude mcp add-json things '{"command":"uvx","args":["things-mcp"]}'

To make it available globally (across all projects), add `-s user`:

claude mcp add-json -s user things '{"command":"uvx","args":["things-mcp"]}'

Verify it's working

After installation: - If using Claude Desktop, you should see "Things MCP" in the "Search and tools" list - Try asking: "What's in my Things inbox?"

Sample Usage with Claude Desktop

* "What's on my todo list today?" * "Create a todo to pack for my beach vacation next week, include a packing checklist." * "Evaluate my current todos using the Eisenhower matrix." * "Help me conduct a GTD-style weekly review using Things." * "Show me tasks that haven't been modified in over a month."

Tips

* Create a project in Claude with custom instructions that explains how you use Things and organize areas, projects, tags, etc. Tell Claude what information you want included when it creates a new task (eg asking it to include relevant details in the task description might be helpful). * Try adding another MCP server that gives Claude access to your calendar. This will let you ask Claude to block time on your calendar for specific tasks, create todos from upcoming calendar events (eg prep for a meeting), etc. * Use task ages to identify stale items: "Which tasks in my Anytime list are older than 2 weeks?"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 325 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Things MCP Server
  2. This [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server lets you use ChatGPT, Codex, Claude Desktop, and other MCP clients to interact with your task management data in [Things 3](https://culturedcode.com/things) from Cultured Code. You can ask your assistant to create tasks, analyze projects, help manage priorities, and more.
  3. This server leverages the [Things.py](https://github.com/thingsapi/things.py) library and the [Things URL Scheme](https://culturedcode.com/things/help/url-scheme/).
  4. ## Support the Project
  5. If you find this project helpful, consider supporting its development:
  6. [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/haldick)
  7. ## Features
  8. - Access to all major Things lists (Inbox, Today, Upcoming, etc.)
  9. - Project and area management
  10. - Tag operations
  11. - Advanced search capabilities
  12. - Recent items
  13. - Detailed item information including checklists
  14. - Support for nested data (projects within areas, todos within projects)
  15. - Someday project filtering: tasks in Someday projects are automatically excluded from Today, Upcoming, and Anytime views, matching Things UI behavior
  16. ## Installation
  17. ### Prerequisites
  18. - macOS (Things 3 is Mac-only)
  19. - Things 3 app with "Enable Things URLs" turned on (Settings → General)
  20. - An MCP client, such as the ChatGPT desktop app, Codex, Claude Desktop, or Claude Code
  21. - [uv](https://docs.astral.sh/uv/) Python package manager: `brew install uv`
  22. ### Install via uvx (Any MCP Client)
  23. Things MCP is published on PyPI and can be run directly with `uvx`:
  24. ```bash
  25. uvx things-mcp
  26. ```
  27. Configure your MCP client to use `uvx` with `things-mcp` as the argument.
  28. ### Claude Desktop
  29. #### Option 1: One-Click Install (Recommended)
  30. 1. Download the latest file from the [releases page](https://github.com/hald/things-mcp/releases)
  31. 2. Double-click the `.mcpb` file
  32. 3. Done!
  33. #### Option 2: Manual Config
  34. 1. Go to **Claude → Settings → Developer → Edit Config**
  35. 2. Add the Things server:
  36. ```json
  37. {
  38. "mcpServers": {
  39. "things": {
  40. "command": "uvx",
  41. "args": ["things-mcp"]
  42. }
  43. }
  44. }
  45. ```
  46. 3. Save and restart Claude Desktop
  47. ### Claude Code
  48. ```bash
  49. claude mcp add-json things '{"command":"uvx","args":["things-mcp"]}'
  50. ```
  51. To make it available globally (across all projects), add `-s user`:
  52. ```bash
  53. claude mcp add-json -s user things '{"command":"uvx","args":["things-mcp"]}'
  54. ```
  55. ### ChatGPT Desktop and Codex
  56. The ChatGPT desktop app, Codex CLI, and Codex IDE extension share the same local MCP configuration. The quickest way to add Things MCP is with the Codex CLI:
  57. ```bash
  58. codex mcp add things -- uvx things-mcp
  59. ```
  60. Confirm that the server is configured:
  61. ```bash
  62. codex mcp list
  63. ```
  64. You can also configure it in the ChatGPT desktop app:
  65. 1. Open **Settings → MCP servers**
  66. 2. Select **Add server**
  67. 3. Enter `things` as the name, choose **STDIO**, and enter the result of `which uvx` as the command to launch (should look similar to /opt/homebrew/bin/uvx)
  68. 4. Enter `things-mcp` under arguments
  69. 5. Save the server and select **Restart**
  70. > [!IMPORTANT]
  71. > When using the ChatGPT desktop client, you must use **Work** mode to access Things MCP. Select **ChatGPT** from the top-left menu, then choose **Work** from the toggle at the top of the page. Regular **Chat** mode does not use locally configured MCP tools. You can also select the separate **Codex** view, which shares the same MCP configuration.
  72. In ChatGPT Work or Codex, type `/mcp` to check that the Things server is connected, then try asking, "What's in my Things inbox?"
  73. This local setup does not work in ChatGPT on the web because the web client does not read local Codex MCP configuration. See [OpenAI's MCP documentation](https://developers.openai.com/codex/mcp/) and [ChatGPT Work and Codex](https://help.openai.com/en/articles/20001275-chatgpt-work-and-codex) for current availability and interface details.
  74. ### Verify it's working
  75. After installation:
  76. - If using Claude Desktop, you should see "Things MCP" in the "Search and tools" list
  77. - If using ChatGPT Work or Codex, type `/mcp` and confirm that the Things server is connected
  78. - Try asking: "What's in my Things inbox?"
  79. ### Sample Usage with Claude Desktop
  80. * "What's on my todo list today?"
  81. * "Create a todo to pack for my beach vacation next week, include a packing checklist."
  82. * "Evaluate my current todos using the Eisenhower matrix."
  83. * "Help me conduct a GTD-style weekly review using Things."
  84. * "Show me tasks that haven't been modified in over a month."
  85. #### Tips
  86. * Create a project in Claude with custom instructions that explains how you use Things and organize areas, projects, tags, etc. Tell Claude what information you want included when it creates a new task (eg asking it to include relevant details in the task description might be helpful).
  87. * Try adding another MCP server that gives Claude access to your calendar. This will let you ask Claude to block time on your calendar for specific tasks, create todos from upcoming calendar events (eg prep for a meeting), etc.
  88. * Use task ages to identify stale items: "Which tasks in my Anytime list are older than 2 weeks?"
  89. ## Available Tools
  90. ### List Views
  91. - `get-inbox` - Get todos from Inbox
  92. - `get-today` - Get todos due today
  93. - `get-upcoming` - Get upcoming todos
  94. - `get-anytime` - Get todos from Anytime list
  95. - `get-someday` - Get todos from Someday list, including tasks in Someday projects
  96. - `get-logbook` - Get completed and canceled todos, optionally for one project
  97. - `get-trash` - Get trashed todos
  98. ### Basic Operations
  99. - `get-todos` - Get todos, optionally filtered by project
  100. - `get-projects` - Get all projects
  101. - `get-areas` - Get all areas
  102. ### Tag Operations
  103. - `get-tags` - Get all tags
  104. - `get-tagged-items` - Get items with a specific tag
  105. - `get-tag-usage` - Report how many items use each tag, sorted by usage; flag unused tags for cleanup
  106. ### Search Operations
  107. - `search-todos` - Simple search by title/notes
  108. - `search-advanced` - Advanced search with multiple filters
  109. ### Time-based Operations
  110. - `get-recent` - Get open items created within a rolling time window
  111. ### Things URL Scheme Operations
  112. - `add-todo` - Create a new todo
  113. - `add-project` - Create a new project
  114. - `add-area` - Create a new Area (via AppleScript; Things URL scheme has no add-area command)
  115. - `update-area` - Update an existing Area: rename or set tags (via AppleScript)
  116. - `update-todo` - Update an existing todo
  117. - `bulk-update-todos` - Apply the same update to many todos in a single operation
  118. - `update-project` - Update an existing project
  119. - `show-item` - Show a specific item or list in Things
  120. - `search-items` - Search for items in Things
  121. ## Tool Parameters
  122. ### Pagination (most read tools)
  123. The list/search read tools (`get-inbox`, `get-today`, `get-upcoming`, `get-anytime`, `get-someday`, `get-logbook`, `get-trash`, `get-todos`, `get-projects`, `get-areas`, `get-tags`, `get-tagged-items`, `get-headings`, `search-todos`, `search-advanced`, `get-recent`) accept optional pagination:
  124. - `limit` - Maximum number of items to return (default: all; `get-logbook` defaults to 50)
  125. - `offset` - Number of items to skip from the start (default: 0)
  126. When neither is set, output is unchanged. When set, a `Showing X-Y of Z items` header is prepended so you know how much more there is. An `offset` past the end is reported distinctly from an empty result.
  127. These same read tools also return **structured content** alongside the human-readable text: MCP clients receive the raw item dicts plus `count`/`total`/`offset`/`limit` under `structured_content`, so data can be consumed programmatically without parsing the formatted text.
  128. ### get-todos
  129. - `project_uuid` (optional) - Filter todos by project
  130. - `include_items` (optional, default: true) - Include checklist items
  131. ### get-projects / get-areas / get-tags
  132. - `include_items` (optional, default: false) - Include contained items
  133. ### search-advanced
  134. - `status` - Filter by status (incomplete/completed/canceled)
  135. - `start_date` - Filter by start date (YYYY-MM-DD)
  136. - `deadline` - Filter by deadline (YYYY-MM-DD)
  137. - `tag` - Filter by tag
  138. - `area` - Filter by area UUID
  139. - `stop_date` - Filter by completion/cancellation date (YYYY-MM-DD, optionally with an operator such as '>=2024-01-01', or 'past'/'future')
  140. - `project` - Filter by project UUID (includes items under the project's headings)
  141. - `type` - Filter by item type (to-do/project/heading)
  142. - `last` - Filter by creation date (e.g., '3d' for last 3 days, '1w' for last week)
  143. ### get-recent
  144. - `period` (required) - Rolling window back from now (e.g., '1d' = the last 24 hours, '1w', '2m', '1y'); months ≈ 30 days, years ≈ 365 days. Returns open (incomplete) items only, newest first
  145. ### get-logbook
  146. - `period` (optional, default: '7d') - Look-back window by completion date. Accepts `d`/`w`/`m`/`y` (e.g., '3d', '1w', '2m', '1y'); months ≈ 30 days, years ≈ 365 days
  147. - `limit` (optional, default: 50) - Maximum number of items to return
  148. - `project_uuid` (optional) - Only return items from this project, including items under its headings
  149. Returns both completed and canceled items; each item's `status` tells them apart.
  150. ### get-tag-usage
  151. - `only_unused` (optional, default: false) - Return only tags that no item references (cleanup candidates)
  152. ### update-todo (checklist & tags)
  153. - `tags` - Replace all tags on the todo
  154. - `add_tags` - Append tags without removing existing ones
  155. - `checklist_items` - Replace the entire checklist with this list; pass an empty list (`[]`) to clear it. Omit it to leave the checklist unchanged
  156. - `prepend_checklist_items` - Add these items to the top of the checklist
  157. - `append_checklist_items` - Add these items to the bottom of the checklist
  158. ### bulk-update-todos
  159. Applies the same change to every todo in `ids` in a single operation. Requires the Things auth token to be enabled (Things → Settings → General → Enable Things URLs → Manage); the server reads it automatically.
  160. - `ids` (required) - List of todo UUIDs to update
  161. - `list` / `list_id` - Move all into a project/area (by title or UUID)
  162. - `tags` / `add_tags` - Replace or append tags on all
  163. - `when` - Reschedule all (keyword or YYYY-MM-DD)
  164. - `deadline` - Set deadline on all (YYYY-MM-DD)
  165. - `heading` / `heading_id` - Move all under a heading (by title or UUID)
  166. - `completed` / `canceled` - Mark all completed or canceled
  167. ### Scheduling with Reminders (add-todo, add-project, update-todo, update-project)
  168. - `when` - Accepts multiple formats:
  169. - Keywords: `today`, `tomorrow`, `evening`, `anytime`, `someday`
  170. - Date: `YYYY-MM-DD` (e.g., `2024-01-15`)
  171. - DateTime with reminder: `YYYY-MM-DD@HH:MM` (e.g., `2024-01-15@14:30`)
  172. ## Troubleshooting
  173. If it's not working:
  174. 1. **Make sure Things 3 is installed and has been opened at least once**
  175. - The Things database needs to exist for the server to work
  176. 2. **Check that "Enable Things URLs" is turned on**
  177. - Open Things → Settings → General → Enable Things URLs
  178. 3. **Claude Desktop can't find `uvx`**
  179. - Install uv globally with Homebrew (`brew install uv`)
  180. - **Alternative**: Use the full path to `uvx` in your config. Find it with `which uvx` (typically `/Users/USERNAME/.local/bin/uvx`)
  181. ## Development
  182. ### Running Tests
  183. The project includes a comprehensive unit test suite for the URL scheme and formatter modules.
  184. ```bash
  185. # Install test dependencies
  186. uv sync --extra test
  187. # Run all tests
  188. uv run pytest
  189. # Run tests with verbose output
  190. uv run pytest -v
  191. # Run a specific test file
  192. uv run pytest tests/test_url_scheme.py
  193. # Run tests matching a pattern
  194. uv run pytest -k "test_add_todo"
  195. ```
  196. ### MCP Integration Test
  197. The project includes an integration test plan that can be executed by Claude (via Claude Cowork or Claude Code) to verify all MCP tools work correctly against a live Things database.
  198. See [`docs/mcp_integration_test_plan.md`](docs/mcp_integration_test_plan.md) for the full test plan.
  199. ### Project Structure
  200. ```
  201. things-mcp/
  202. ├── src/things_mcp/ # Main package
  203. │ ├── __init__.py # Package exports
  204. │ ├── __main__.py # Entry point for python -m
  205. │ ├── server.py # MCP server implementation
  206. │ ├── url_scheme.py # Things URL scheme implementation
  207. │ └── formatters.py # Data formatting utilities
  208. ├── tests/ # Unit tests
  209. │ ├── conftest.py # Test fixtures and configuration
  210. │ ├── test_url_scheme.py
  211. │ ├── test_formatters.py
  212. │ ├── test_someday_filtering.py
  213. │ └── test_mcp_server_filtering.py
  214. ├── docs/ # Documentation
  215. │ └── mcp_integration_test_plan.md # Claude-executable integration test
  216. ├── manifest.json # MCPB package manifest
  217. ├── build_mcpb.sh # MCPB package build script
  218. ├── pyproject.toml # Project dependencies, build config, and pytest config
  219. ├── .env.example # Sample environment configuration
  220. └── run.sh # Convenience runner script
  221. ```
  222. ### HTTP Transport
  223. By default, the server uses stdio transport for communication with MCP clients. For remote access scenarios, you can run the server with HTTP transport.
  224. #### Configuration
  225. Set these environment variables to enable HTTP transport:
  226. | Variable | Default | Description |
  227. |----------|---------|-------------|
  228. | `THINGS_MCP_TRANSPORT` | `stdio` | Transport type: `stdio` or `http` |
  229. | `THINGS_MCP_HOST` | `127.0.0.1` | HTTP server bind address |
  230. | `THINGS_MCP_PORT` | `8000` | HTTP server port |
  231. #### Example
  232. ```bash
  233. # Using uvx
  234. THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uvx things-mcp
  235. # Or from source
  236. THINGS_MCP_TRANSPORT=http THINGS_MCP_HOST=0.0.0.0 THINGS_MCP_PORT=8000 uv run things-mcp
  237. ```
  238. See `.env.example` for a sample configuration file.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.