<div align="center">
# Things 3 MCP Server
</div>
This [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server lets you use Claude Desktop to interact with your task management data in [Things 3](https://culturedcode.com/things). You can ask Claude or your MCP client of choice to create tasks, analyze projects, help manage priorities, and more.
This MCP server leverages a combination of the [Things.py](https://github.com/thingsapi/things.py) library and [Things 3’s AppleScript support](https://culturedcode.com/things/support/articles/4562654/), enabling reading and writing to Things 3.
## Why Things MCP?
This MCP server unlocks the power of AI for your task management:
- **Natural Language Task Creation**: Ask Claude to create richly-detailed tasks and descriptions in natural language
- **Smart Task Analysis**: Let Claude explore your project lists and focus areas and provide insights into your work
- **GTD & Productivity Workflows**: Let Claude help you implement productivity and prioritisation systems
- **Seamless Integration**: Works directly with your existing Things 3 data
## Features
- Access to all major Things lists (Inbox, Today, Upcoming, Logbook, Someday, etc.)
- Project and Area management and assignment
- Tagging operations for tasks and projects
- Advanced search capabilities
- Recent items tracking
- Support for nested data (projects within areas, todos within projects)
- Checklist/Subtask support - Read and display existing checklist items from todos
## Installation
#### Prerequisites
* Python 3.12+
* Claude Desktop
* Things 3 for MacOS
#### Step 1: Install the package
**Option A: Install from PyPI in a virtual environment (recommended)**
```bash
# Create a virtual environment in your home directory
python3 -m venv ~/.venvs/things3-mcp-env
source ~/.venvs/things3-mcp-env/bin/activate
# Install the package
pip install Things3-MCP-server==2.0.0
```
**Option B: Install from source (for development/contributors)**
```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Restart your terminal afterwards
# Clone and install the package with development dependencies
git clone https://github.com/rossshannon/Things3-MCP
cd Things3-MCP
uv venv
uv pip install -e ".[dev]" # Install in development mode with extra dependencies
```
### Step 2: Configure Claude Desktop
Edit the Claude Desktop configuration file:
```bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
Add the Things server to the mcpServers key in the configuration file:
**Option A: Using PyPI package in virtual environment**
```json
{
"mcpServers": {
"things": {
"command": "~/.venvs/things3-mcp-env/bin/Things3-MCP-server"
}
}
}
```
**Option B: Using source installation (for development/contributors)**
```json
{
"mcpServers": {
"things": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/FOLDER/Things3-MCP",
"run",
"Things3-MCP-server"
]
}
}
}
```
### Step 3: Restart Claude Desktop
Restart the Claude Desktop app to enable the integration.
### Sample Usage with Claude Desktop
* “What’s on my todo list today?”
* “Create a todo to prepare for each of my 1-on-1s next week”
* “Evaluate my todos scheduled for today using the Eisenhower matrix.”
* “Help me conduct a GTD-style weekly review using Things.”
#### 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 (e.g., asking it to include relevant details in the task description, whether to use emojis, etc.).
* Try combining this with 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 tasks that relate to upcoming calendar events (e.g., prep for a meeting), etc.
### Available Tools
#### List Views
- `get_inbox` - Get todos from Inbox
- `get_today` - Get todos due today
- `get_upcoming` - Get upcoming todos
- `get_anytime` - Get todos from Anytime list
- `get_someday` - Get todos from Someday list
- `get_logbook` - Get completed todos
- `get_trash` - Get trashed todos
#### Basic Operations
- `get_todos` - Get todos, optionally filtered by project
- `get_projects` - Get all projects
- `get_areas` - Get all areas
#### Tag Operations
- `get_tags` - Get all tags
- `get_tagged_items` - Get items with a specific tag
#### Search Operations
- `search_todos` - Simple search by title/notes
- `search_advanced` - Advanced search with multiple filters
#### Time-based Operations
- `get_recent` - Get recently created items
#### Modification Operations
- `add_todo` - Create a new todo with full parameter support
- `add_project` - Create a new project with tags and todos
- `update_todo` - Update an existing todo
- `update_project` - Update an existing project
- `show_item` - Show a specific item or list in Things
- `search_items` - Search for items in Things
## Tool Parameters
### get_todos
- `project_uuid` (optional) - Filter todos by project
### get_projects / get_areas / get_tags
- `include_items` (optional, default: false) - Include contained items
### search_advanced
- `status` - Filter by status (incomplete/completed/canceled)
- `start_date` - Filter by start date (YYYY-MM-DD)
- `deadline` - Filter by deadline (YYYY-MM-DD)
- `tag` - Filter by tag
- `area` - Filter by area UUID
- `type` - Filter by item type (to-do/project/heading)
### get_recent
- `period` - Time period (e.g., '3d', '1w', '2m', '1y')
- `limit` - Maximum number of items to return
### add_todo
- `title` - Title of the todo
- `notes` (optional) - Notes for the todo (supports Markdown formatting including checkboxes like `- [ ] Task`)
- `when` (optional) - When to schedule the todo (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)
- `deadline` (optional) - Deadline for the todo (YYYY-MM-DD)
- `tags` (optional) - Tags to apply to the todo
- `list_title` or `list_id` (optional) - Title or ID of project/area to add to
- **Note**: While Things’ native checklist feature (i.e., subtasks) cannot be created via AppleScript, you and your LLMs can use Markdown checkboxes in the notes field to achieve similar functionality. 
### update_todo
- `id` - ID of the todo to update
- `title` (optional) - New title
- `notes` (optional) - New notes
- `when` (optional) - When to schedule the todo (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)
- `deadline` (optional) - Deadline for the todo (YYYY-MM-DD)
- `tags` (optional) - New tags
- `completed` (optional) - Mark as completed
- `canceled` (optional) - Mark as canceled
- `project` (optional) - Name of project to move the todo to (must exactly match an existing project title — look them up with `get_projects`)
- `area_title` (optional) - Title of the area to move the todo to (must exactly match an existing area title — look them up with `get_areas`)
### add_project
- `title` - Title of the project
- `notes` (optional) - Notes for the project
- `when` (optional) - When to schedule the project
- `deadline` (optional) - Deadline for the project
- `tags` (optional) - Tags to apply to the project
- `area_title` or `area_id` (optional) - Title or ID of area to add to (must exactly match an existing area title — look them up with `get_areas`)
- `todos` (optional) - Initial todos to create in the project
### update_project
- `id` - ID of the project to update
- `title` (optional) - New title
- `notes` (optional) - New notes
- `when` (optional) - When to schedule the project (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)
- `deadline` (optional) - Deadline for the project (YYYY-MM-DD)
- `tags` (optional) - New tags
- `completed` (optional) - Mark as completed
- `canceled` (optional) - Mark as canceled
### show_item
- `id` - ID of item to show, or one of: inbox, today, upcoming, anytime, someday, logbook
- `query` (optional) - Optional query to filter by
- `filter_tags` (optional) - Optional tags to filter by
## Using Tags
Things will automatically create missing tags when they are added to a task or project. Configure your LLM to do a lookup of your tags first before making changes if you want to control this.
## Development
This project uses `pyproject.toml` to manage dependencies and build configuration. It's built using the [Model Context Protocol](https://modelcontextprotocol.io), which allows Claude to securely access tools and data.
### Development Workflow
#### Setting up a development environment
```bash
# Clone the repository
git clone https://github.com/rossshannon/Things3-MCP
cd Things3-MCP
# Set up a virtual environment with development dependencies
uv venv
uv pip install -e ".[dev]" # Install in development mode with extra dependencies
```
#### Testing changes during development
Run the comprehensive test suite to ensure everything is working as expected:
```bash
# Test the implementation
uv run pytest tests/
```
The tests clean up after themselves and don’t affect your existing data, so you can run them as often as you like.
## Troubleshooting
The server includes error handling for:
- Invalid UUIDs
- Missing required parameters
- Things database access errors
- Data formatting errors
- Authentication token issues
- AppleScript execution failures
### Common Issues
2. **Things app not running**: Make sure the Things app is running on your Mac.
### Checking Logs
All errors are logged and returned with descriptive messages. To review the MCP logs:
```bash
# Follow main logs in real-time
tail -f ~/.things-mcp/logs/things_mcp.log
# Check error logs
tail -f ~/.things-mcp/logs/things_mcp_errors.log
# View structured logs for analysis
cat ~/.things-mcp/logs/things_mcp_structured.json | jq
# Claude Desktop MCP logs
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```
## Acknowledgements
This MCP server was originally based on the Applescript bridge method from [things-mcp](https://github.com/excelsier/things-mcp) by [excelsier](https://github.com/excelsier/), which was in turn based on [things-mcp](https://github.com/hald/things-mcp) by [hald](https://github.com/hald/).
Raw data
{
"_id": null,
"home_page": null,
"name": "Things3-MCP-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "anthropic, apple, claude, fastmcp, macos, mcp, productivity, task-management, things, things3",
"author": null,
"author_email": "Ross Shannon <4503044+rossshannon@users.noreply.github.com>, Yaroslav Krempovych <51231325+excelsior@users.noreply.github.com>, Harald Lindstr\u00f8m <hald@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/1f/31/76d17245c9ff16778a96f376b427626970d1a360f8f15054aebcb7e64a70/things3_mcp_server-2.0.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n\n\n# Things 3 MCP Server\n\n</div>\n\nThis [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server lets you use Claude Desktop to interact with your task management data in [Things 3](https://culturedcode.com/things). You can ask Claude or your MCP client of choice to create tasks, analyze projects, help manage priorities, and more.\n\nThis MCP server leverages a combination of the [Things.py](https://github.com/thingsapi/things.py) library and [Things 3\u2019s AppleScript support](https://culturedcode.com/things/support/articles/4562654/), enabling reading and writing to Things 3.\n\n## Why Things MCP?\n\nThis MCP server unlocks the power of AI for your task management:\n\n- **Natural Language Task Creation**: Ask Claude to create richly-detailed tasks and descriptions in natural language\n- **Smart Task Analysis**: Let Claude explore your project lists and focus areas and provide insights into your work\n- **GTD & Productivity Workflows**: Let Claude help you implement productivity and prioritisation systems\n- **Seamless Integration**: Works directly with your existing Things 3 data\n\n## Features\n\n- Access to all major Things lists (Inbox, Today, Upcoming, Logbook, Someday, etc.)\n- Project and Area management and assignment\n- Tagging operations for tasks and projects\n- Advanced search capabilities\n- Recent items tracking\n- Support for nested data (projects within areas, todos within projects)\n- Checklist/Subtask support - Read and display existing checklist items from todos\n\n## Installation\n\n#### Prerequisites\n* Python 3.12+\n* Claude Desktop\n* Things 3 for MacOS\n\n#### Step 1: Install the package\n\n**Option A: Install from PyPI in a virtual environment (recommended)**\n```bash\n# Create a virtual environment in your home directory\npython3 -m venv ~/.venvs/things3-mcp-env\nsource ~/.venvs/things3-mcp-env/bin/activate\n\n# Install the package\npip install Things3-MCP-server==2.0.0\n```\n\n**Option B: Install from source (for development/contributors)**\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# Restart your terminal afterwards\n\n# Clone and install the package with development dependencies\ngit clone https://github.com/rossshannon/Things3-MCP\ncd Things3-MCP\nuv venv\nuv pip install -e \".[dev]\" # Install in development mode with extra dependencies\n```\n\n### Step 2: Configure Claude Desktop\nEdit the Claude Desktop configuration file:\n```bash\ncode ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n```\n\nAdd the Things server to the mcpServers key in the configuration file:\n\n**Option A: Using PyPI package in virtual environment**\n```json\n{\n \"mcpServers\": {\n \"things\": {\n \"command\": \"~/.venvs/things3-mcp-env/bin/Things3-MCP-server\"\n }\n }\n}\n```\n\n**Option B: Using source installation (for development/contributors)**\n```json\n{\n \"mcpServers\": {\n \"things\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/ABSOLUTE/PATH/TO/PARENT/FOLDER/Things3-MCP\",\n \"run\",\n \"Things3-MCP-server\"\n ]\n }\n }\n}\n```\n\n### Step 3: Restart Claude Desktop\nRestart the Claude Desktop app to enable the integration.\n\n### Sample Usage with Claude Desktop\n* \u201cWhat\u2019s on my todo list today?\u201d\n* \u201cCreate a todo to prepare for each of my 1-on-1s next week\u201d\n* \u201cEvaluate my todos scheduled for today using the Eisenhower matrix.\u201d\n* \u201cHelp me conduct a GTD-style weekly review using Things.\u201d\n\n#### Tips\n* 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 (e.g., asking it to include relevant details in the task description, whether to use emojis, etc.).\n* Try combining this with 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 tasks that relate to upcoming calendar events (e.g., prep for a meeting), etc.\n\n\n### Available Tools\n\n#### List Views\n- `get_inbox` - Get todos from Inbox\n- `get_today` - Get todos due today\n- `get_upcoming` - Get upcoming todos\n- `get_anytime` - Get todos from Anytime list\n- `get_someday` - Get todos from Someday list\n- `get_logbook` - Get completed todos\n- `get_trash` - Get trashed todos\n\n#### Basic Operations\n- `get_todos` - Get todos, optionally filtered by project\n- `get_projects` - Get all projects\n- `get_areas` - Get all areas\n\n#### Tag Operations\n- `get_tags` - Get all tags\n- `get_tagged_items` - Get items with a specific tag\n\n#### Search Operations\n- `search_todos` - Simple search by title/notes\n- `search_advanced` - Advanced search with multiple filters\n\n#### Time-based Operations\n- `get_recent` - Get recently created items\n\n#### Modification Operations\n- `add_todo` - Create a new todo with full parameter support\n- `add_project` - Create a new project with tags and todos\n- `update_todo` - Update an existing todo\n- `update_project` - Update an existing project\n- `show_item` - Show a specific item or list in Things\n- `search_items` - Search for items in Things\n\n## Tool Parameters\n\n### get_todos\n- `project_uuid` (optional) - Filter todos by project\n\n### get_projects / get_areas / get_tags\n- `include_items` (optional, default: false) - Include contained items\n\n### search_advanced\n- `status` - Filter by status (incomplete/completed/canceled)\n- `start_date` - Filter by start date (YYYY-MM-DD)\n- `deadline` - Filter by deadline (YYYY-MM-DD)\n- `tag` - Filter by tag\n- `area` - Filter by area UUID\n- `type` - Filter by item type (to-do/project/heading)\n\n### get_recent\n- `period` - Time period (e.g., '3d', '1w', '2m', '1y')\n- `limit` - Maximum number of items to return\n\n### add_todo\n- `title` - Title of the todo\n- `notes` (optional) - Notes for the todo (supports Markdown formatting including checkboxes like `- [ ] Task`)\n- `when` (optional) - When to schedule the todo (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)\n- `deadline` (optional) - Deadline for the todo (YYYY-MM-DD)\n- `tags` (optional) - Tags to apply to the todo\n- `list_title` or `list_id` (optional) - Title or ID of project/area to add to\n- **Note**: While Things\u2019 native checklist feature (i.e., subtasks) cannot be created via AppleScript, you and your LLMs can use Markdown checkboxes in the notes field to achieve similar functionality. \n\n### update_todo\n- `id` - ID of the todo to update\n- `title` (optional) - New title\n- `notes` (optional) - New notes\n- `when` (optional) - When to schedule the todo (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)\n- `deadline` (optional) - Deadline for the todo (YYYY-MM-DD)\n- `tags` (optional) - New tags\n- `completed` (optional) - Mark as completed\n- `canceled` (optional) - Mark as canceled\n- `project` (optional) - Name of project to move the todo to (must exactly match an existing project title \u2014 look them up with `get_projects`)\n- `area_title` (optional) - Title of the area to move the todo to (must exactly match an existing area title \u2014 look them up with `get_areas`)\n\n### add_project\n- `title` - Title of the project\n- `notes` (optional) - Notes for the project\n- `when` (optional) - When to schedule the project\n- `deadline` (optional) - Deadline for the project\n- `tags` (optional) - Tags to apply to the project\n- `area_title` or `area_id` (optional) - Title or ID of area to add to (must exactly match an existing area title \u2014 look them up with `get_areas`)\n- `todos` (optional) - Initial todos to create in the project\n\n### update_project\n- `id` - ID of the project to update\n- `title` (optional) - New title\n- `notes` (optional) - New notes\n- `when` (optional) - When to schedule the project (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)\n- `deadline` (optional) - Deadline for the project (YYYY-MM-DD)\n- `tags` (optional) - New tags\n- `completed` (optional) - Mark as completed\n- `canceled` (optional) - Mark as canceled\n\n### show_item\n- `id` - ID of item to show, or one of: inbox, today, upcoming, anytime, someday, logbook\n- `query` (optional) - Optional query to filter by\n- `filter_tags` (optional) - Optional tags to filter by\n\n## Using Tags\nThings will automatically create missing tags when they are added to a task or project. Configure your LLM to do a lookup of your tags first before making changes if you want to control this.\n\n## Development\n\nThis project uses `pyproject.toml` to manage dependencies and build configuration. It's built using the [Model Context Protocol](https://modelcontextprotocol.io), which allows Claude to securely access tools and data.\n\n### Development Workflow\n\n#### Setting up a development environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/rossshannon/Things3-MCP\ncd Things3-MCP\n\n# Set up a virtual environment with development dependencies\nuv venv\nuv pip install -e \".[dev]\" # Install in development mode with extra dependencies\n```\n\n#### Testing changes during development\n\nRun the comprehensive test suite to ensure everything is working as expected:\n\n```bash\n# Test the implementation\nuv run pytest tests/\n```\n\nThe tests clean up after themselves and don\u2019t affect your existing data, so you can run them as often as you like.\n\n\n\n## Troubleshooting\n\nThe server includes error handling for:\n- Invalid UUIDs\n- Missing required parameters\n- Things database access errors\n- Data formatting errors\n- Authentication token issues\n- AppleScript execution failures\n\n### Common Issues\n\n2. **Things app not running**: Make sure the Things app is running on your Mac.\n\n### Checking Logs\n\nAll errors are logged and returned with descriptive messages. To review the MCP logs:\n\n```bash\n# Follow main logs in real-time\ntail -f ~/.things-mcp/logs/things_mcp.log\n\n# Check error logs\ntail -f ~/.things-mcp/logs/things_mcp_errors.log\n\n# View structured logs for analysis\ncat ~/.things-mcp/logs/things_mcp_structured.json | jq\n\n# Claude Desktop MCP logs\ntail -n 20 -f ~/Library/Logs/Claude/mcp*.log\n```\n\n## Acknowledgements\n\nThis MCP server was originally based on the Applescript bridge method from [things-mcp](https://github.com/excelsier/things-mcp) by [excelsier](https://github.com/excelsier/), which was in turn based on [things-mcp](https://github.com/hald/things-mcp) by [hald](https://github.com/hald/).\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "MCP server for Things 3 with read/write support for tasks, projects, areas and tags.",
"version": "2.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/rossshannon/things-fastmcp/issues",
"Documentation": "https://github.com/rossshannon/things-fastmcp#readme",
"Homepage": "https://github.com/rossshannon/things-fastmcp"
},
"split_keywords": [
"anthropic",
" apple",
" claude",
" fastmcp",
" macos",
" mcp",
" productivity",
" task-management",
" things",
" things3"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d49c17c39be65411972d3ccdb6868f20e8e18819c5c0c8c4b8f782fe16ee5057",
"md5": "046a3d6ed1e837932c80217bb9c2f083",
"sha256": "166747431bb79c7bd36c5f53146c0e8302da085afca6c77cb342eb8db7d66768"
},
"downloads": -1,
"filename": "things3_mcp_server-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "046a3d6ed1e837932c80217bb9c2f083",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 23134,
"upload_time": "2025-08-01T14:26:40",
"upload_time_iso_8601": "2025-08-01T14:26:40.748265Z",
"url": "https://files.pythonhosted.org/packages/d4/9c/17c39be65411972d3ccdb6868f20e8e18819c5c0c8c4b8f782fe16ee5057/things3_mcp_server-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1f3176d17245c9ff16778a96f376b427626970d1a360f8f15054aebcb7e64a70",
"md5": "f7c45d5969035be89cefaca7e310ca3c",
"sha256": "de7f0aac8c34593007e60447516a44e8b7042227f49b32bb76888eebb49b0564"
},
"downloads": -1,
"filename": "things3_mcp_server-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "f7c45d5969035be89cefaca7e310ca3c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 25095,
"upload_time": "2025-08-01T14:26:42",
"upload_time_iso_8601": "2025-08-01T14:26:42.135504Z",
"url": "https://files.pythonhosted.org/packages/1f/31/76d17245c9ff16778a96f376b427626970d1a360f8f15054aebcb7e64a70/things3_mcp_server-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 14:26:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rossshannon",
"github_project": "things-fastmcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "things3-mcp-server"
}
JSON
