<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.5
```
**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
#### Random Sampling (for LLM Enrichment)
- `get_random_inbox` - Get a random sample of todos from Inbox
- `get_random_anytime` - Get a random sample of items from Anytime list
- `get_random_todos` - Get a random sample of todos, optionally filtered by project
#### 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
### Random Sampling Tools
- `get_random_inbox(count=5)` - Get random sample from Inbox
- `get_random_anytime(count=5)` - Get random sample from Anytime list
- `get_random_todos(project_uuid=None, count=5)` - Get random sample of todos, optionally from specific project
### 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` (optional) - Title of project/area to add to (must exactly match existing name)
- `list_id` (optional) - ID of project/area to add to (takes priority over list_title if both provided)
- **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
- `list_name` (optional) - Name of built-in list, project, or area to move the todo to. For built-in lists use: "Inbox", "Today", "Anytime", "Someday". For projects/areas, use the exact name.
- `list_id` (optional) - ID of project/area to move the todo to (takes priority over list_name if both provided)
### 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
## Usage Examples
### Creating Todos with List Assignment
```python
# Create todo in Inbox (default)
add_todo(title="Review quarterly report")
# Create todo in a built-in list
add_todo(title="Call dentist", when="today")
add_todo(title="Plan vacation", when="someday")
# Create todo in a project by name
add_todo(title="Design new logo", list_title="Website Redesign")
# Create todo in a project by ID (more precise, recommended for automation)
add_todo(title="Write documentation", list_id="ABC123DEF456")
# When both are provided, list_id takes priority
add_todo(
title="Important task",
list_id="ABC123DEF456", # This will be used
list_title="Other Project" # This will be ignored
)
```
### Moving Todos Between Lists
```python
# Move to built-in list
update_todo(id="TODO123", list_name="Today")
update_todo(id="TODO456", list_name="Someday")
# Move to project by name
update_todo(id="TODO789", list_name="Website Redesign")
# Move to project by ID (recommended for precision)
update_todo(id="TODO101", list_id="ABC123DEF456")
```
### When to Use ID vs Title
- **Use `list_title`/`list_name`** when:
- Working interactively with human-readable names
- You're certain the name is unique and won't change
- Creating simple scripts or one-off tasks
- **Use `list_id`** when:
- Building automation or applications
- You need precision and reliability
- Working with projects/areas that might have similar names
## 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.
## LLM Enrichment Workflows
The random sampling tools (`get_random_inbox`, `get_random_anytime`, `get_random_todos`) are designed for iterative task improvement workflows where you want to gradually enhance your todo items using AI assistance.
### Use Cases
**Incremental Task Enhancement**
- Pull 5 random todos from your Inbox to add better descriptions, break down into subtasks, or estimate time requirements
- Sample from your Anytime list to identify tasks that could benefit from better scheduling or prioritization
- Avoid downloading hundreds of tasks into context when you only need a few
**Content Enrichment**
- Add or improve context and suggest more actionable language
- Add context, dependencies, or next steps to existing todos
- Standardize formatting across your task descriptions
- Find tasks that might be too vague or overly complex
- Discover todos that could be automated or delegated
## 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
# Run all tests (116 tests, ~3-4 minutes)
uv run pytest
# Run tests with coverage report
uv run pytest --cov=things_mcp --cov-report=term-missing
# Run specific test file
uv run pytest tests/test_list_assignment_operations.py
# Run tests with minimal output
uv run pytest -q
# Run tests matching a pattern
uv run pytest -k "error_handling"
```
**Test Configuration:**
- **116 comprehensive tests** covering all functionality
- **Automatic cleanup** - tests don't affect your existing Things data
- **Edge case coverage** - malformed UUIDs, timeouts, error conditions
- **Integration testing** - tests against real Things app
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-fastmcp) 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/c1/ab/e2d7709d7f37afe06140b4d9db3893596b2abb5857b724af1bdb4083591f/things3_mcp_server-2.0.5.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.5\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#### Random Sampling (for LLM Enrichment)\n- `get_random_inbox` - Get a random sample of todos from Inbox\n- `get_random_anytime` - Get a random sample of items from Anytime list\n- `get_random_todos` - Get a random sample of todos, optionally filtered by project\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### Random Sampling Tools\n- `get_random_inbox(count=5)` - Get random sample from Inbox\n- `get_random_anytime(count=5)` - Get random sample from Anytime list\n- `get_random_todos(project_uuid=None, count=5)` - Get random sample of todos, optionally from specific project\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` (optional) - Title of project/area to add to (must exactly match existing name)\n- `list_id` (optional) - ID of project/area to add to (takes priority over list_title if both provided)\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- `list_name` (optional) - Name of built-in list, project, or area to move the todo to. For built-in lists use: \"Inbox\", \"Today\", \"Anytime\", \"Someday\". For projects/areas, use the exact name.\n- `list_id` (optional) - ID of project/area to move the todo to (takes priority over list_name if both provided)\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## Usage Examples\n\n### Creating Todos with List Assignment\n\n```python\n# Create todo in Inbox (default)\nadd_todo(title=\"Review quarterly report\")\n\n# Create todo in a built-in list\nadd_todo(title=\"Call dentist\", when=\"today\")\nadd_todo(title=\"Plan vacation\", when=\"someday\")\n\n# Create todo in a project by name\nadd_todo(title=\"Design new logo\", list_title=\"Website Redesign\")\n\n# Create todo in a project by ID (more precise, recommended for automation)\nadd_todo(title=\"Write documentation\", list_id=\"ABC123DEF456\")\n\n# When both are provided, list_id takes priority\nadd_todo(\n title=\"Important task\",\n list_id=\"ABC123DEF456\", # This will be used\n list_title=\"Other Project\" # This will be ignored\n)\n```\n\n### Moving Todos Between Lists\n\n```python\n# Move to built-in list\nupdate_todo(id=\"TODO123\", list_name=\"Today\")\nupdate_todo(id=\"TODO456\", list_name=\"Someday\")\n\n# Move to project by name\nupdate_todo(id=\"TODO789\", list_name=\"Website Redesign\")\n\n# Move to project by ID (recommended for precision)\nupdate_todo(id=\"TODO101\", list_id=\"ABC123DEF456\")\n```\n\n### When to Use ID vs Title\n\n- **Use `list_title`/`list_name`** when:\n - Working interactively with human-readable names\n - You're certain the name is unique and won't change\n - Creating simple scripts or one-off tasks\n\n- **Use `list_id`** when:\n - Building automation or applications\n - You need precision and reliability\n - Working with projects/areas that might have similar names\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## LLM Enrichment Workflows\n\nThe random sampling tools (`get_random_inbox`, `get_random_anytime`, `get_random_todos`) are designed for iterative task improvement workflows where you want to gradually enhance your todo items using AI assistance.\n\n### Use Cases\n\n**Incremental Task Enhancement**\n- Pull 5 random todos from your Inbox to add better descriptions, break down into subtasks, or estimate time requirements\n- Sample from your Anytime list to identify tasks that could benefit from better scheduling or prioritization\n- Avoid downloading hundreds of tasks into context when you only need a few\n\n**Content Enrichment**\n- Add or improve context and suggest more actionable language\n- Add context, dependencies, or next steps to existing todos\n- Standardize formatting across your task descriptions\n- Find tasks that might be too vague or overly complex\n- Discover todos that could be automated or delegated\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# Run all tests (116 tests, ~3-4 minutes)\nuv run pytest\n\n# Run tests with coverage report\nuv run pytest --cov=things_mcp --cov-report=term-missing\n\n# Run specific test file\nuv run pytest tests/test_list_assignment_operations.py\n\n# Run tests with minimal output\nuv run pytest -q\n\n# Run tests matching a pattern\nuv run pytest -k \"error_handling\"\n```\n\n**Test Configuration:**\n- **116 comprehensive tests** covering all functionality\n- **Automatic cleanup** - tests don't affect your existing Things data\n- **Edge case coverage** - malformed UUIDs, timeouts, error conditions\n- **Integration testing** - tests against real Things app\n\nThe tests clean up after themselves and don't 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-fastmcp) 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.5",
"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": "b76c9e157ef563fc01965c6c01c33f77e139dc0c62df657d0797d26f9aadebdc",
"md5": "9481d2823c81769c48b13fe61bf87f58",
"sha256": "8ef1ad4f17244aed8d1c696bcf91d8cae37f3b751350d886b2ab95d4b7cfe67e"
},
"downloads": -1,
"filename": "things3_mcp_server-2.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9481d2823c81769c48b13fe61bf87f58",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 25956,
"upload_time": "2025-08-21T13:18:00",
"upload_time_iso_8601": "2025-08-21T13:18:00.516266Z",
"url": "https://files.pythonhosted.org/packages/b7/6c/9e157ef563fc01965c6c01c33f77e139dc0c62df657d0797d26f9aadebdc/things3_mcp_server-2.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c1abe2d7709d7f37afe06140b4d9db3893596b2abb5857b724af1bdb4083591f",
"md5": "681695cbcdf12a08749f568713dc1086",
"sha256": "08c8b38116e58ad94dbec1b85c9a2e5c7f14f8b98e495d6c05877dd6791274f8"
},
"downloads": -1,
"filename": "things3_mcp_server-2.0.5.tar.gz",
"has_sig": false,
"md5_digest": "681695cbcdf12a08749f568713dc1086",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 28046,
"upload_time": "2025-08-21T13:18:01",
"upload_time_iso_8601": "2025-08-21T13:18:01.575543Z",
"url": "https://files.pythonhosted.org/packages/c1/ab/e2d7709d7f37afe06140b4d9db3893596b2abb5857b724af1bdb4083591f/things3_mcp_server-2.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 13:18:01",
"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
