| Name | things3-mcp JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | A server implementation for interacting with Things3 app on macOS through Claude AI |
| upload_time | 2025-07-21 21:26:47 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
claude
macos
mcp
task-management
things3
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MCP Server for Things3
A robust MCP (Model Context Protocol) server providing comprehensive integration with Things3, allowing you to create, manage, and search tasks and projects through the MCP protocol. Features ID-based task management, JSON-based AppleScript integration, and Things3 philosophy guidance.
## Features
- ✅ **Create Projects & Todos**: Full metadata support with checklists, tags, and dates
- ✅ **Update Tasks**: Modify any task property using task IDs with auth token support
- ✅ **View Tasks**: List tasks from Inbox, Today, Upcoming, Anytime, or Projects
- ✅ **Complete Tasks**: Mark todos as completed using their ID
- ✅ **Search Functionality**: Search through all todos by title or content
- ✅ **Things3 Philosophy**: Built-in guidance for effective task management
- ✅ **JSON Integration**: Reliable data extraction using Foundation framework
- ✅ **Today Overload Warning**: Alerts when Today list exceeds 4 items
## Installation
### Prerequisites
- macOS with Things3 installed
- Python 3.10+
- Things3 running (for real-time operations)
- Things3 auth token (for update operations)
### Install the Server
1. Clone this repository:
```bash
git clone <repository-url>
cd mcp-things3
```
2. Install using pip:
```bash
pip install -e .
```
3. The server will be available as `mcp-server-things3`
### Auth Token Setup
For update operations, you need to set your Things3 auth token:
1. Open Things3
2. Go to Settings → General → Enable Things URLs → Manage
3. Copy your auth token
4. Set the environment variable:
```bash
export THINGS3_AUTH_TOKEN="your-token-here"
```
## Tools Available
### View Operations
#### `view-inbox`
View all todos in the Things3 inbox.
- **Parameters**: None
- **Returns**: List of inbox todos with IDs, titles, tags, and metadata
#### `view-todos`
View all todos in today's list with overload warning.
- **Parameters**: None
- **Returns**: List of today's todos with IDs and warning if >4 items
#### `view-upcoming`
View scheduled future tasks in Things3's Upcoming list.
- **Parameters**: None
- **Returns**: Tasks organized by date, showing what's hibernating until scheduled
#### `view-anytime`
View all unscheduled active tasks in Things3's Anytime list.
- **Parameters**: None
- **Returns**: Tasks organized by project/area, ready whenever you are
#### `view-projects`
View all projects in Things3.
- **Parameters**: None
- **Returns**: List of all projects with IDs and titles
### Creation Operations
#### `create-things3-project`
Creates a new project in Things3.
- **Required**: `title` (string)
- **Optional**:
- `notes` (string)
- `area` (string)
- `when` (string) - Date/time to start
- `deadline` (string) - Due date
- `tags` (array of strings)
**Example**:
```json
{
"title": "Website Redesign",
"notes": "Complete overhaul of company website",
"area": "Work",
"deadline": "2024-03-15",
"tags": ["urgent", "web-dev"]
}
```
#### `create-things3-todo`
Creates a new to-do in Things3.
- **Required**: `title` (string)
- **Optional**:
- `notes` (string)
- `when` (string) - Date/time to start
- `deadline` (string) - Due date
- `checklist` (array of strings)
- `tags` (array of strings)
- `list` (string) - Project or area to assign to
- `heading` (string) - Group under this heading
**Example**:
```json
{
"title": "Review design mockups",
"notes": "Check the new homepage designs",
"list": "Website Redesign",
"deadline": "2024-02-20",
"tags": ["review"],
"checklist": ["Check mobile responsiveness", "Verify brand guidelines", "Test accessibility"]
}
```
### Management Operations
#### `update-things3-todo`
Update an existing to-do in Things3. Requires auth token.
- **Required**: `id` (string) - Todo ID from view/search results
- **Optional**: All todo fields (title, notes, when, deadline, tags, etc.)
- **Special**: `completed`, `canceled` (boolean) for status changes
- **Returns**: Success message with philosophical guidance
**Example**:
```json
{
"id": "2DCAbD81QBc6oQbzaNjFhM",
"when": "tomorrow",
"tags": ["urgent", "review"]
}
```
#### `complete-things3-todo`
Mark a todo as completed using its ID.
- **Required**: `id` (string) - Todo ID from view/search results
- **Returns**: Success/failure message
**Example**:
```json
{
"id": "2DCAbD81QBc6oQbzaNjFhM"
}
```
#### `search-things3-todos`
Search for todos by title or content.
- **Required**: `query` (string) - Search term
- **Returns**: List of matching todos with status and metadata
**Example**:
```json
{
"query": "website"
}
```
## Integration with Claude
This MCP server is designed to work seamlessly with Claude AI. Once configured, you can use natural language to manage your Things3 tasks:
- "Create a project called 'Q1 Planning' with a deadline of March 31st"
- "Add a todo to review the budget with a checklist of tasks"
- "Show me all my tasks for today"
- "Mark the 'Call client' task as completed"
- "Search for all todos related to the website project"
## Configuration
### MCP Client Configuration
Add to your MCP client configuration (e.g., Claude Desktop config):
```json
{
"mcpServers": {
"things3": {
"command": "mcp-server-things3",
"args": []
}
}
}
```
### Things3 Setup
1. Ensure Things3 is installed and running
2. Grant necessary permissions when prompted for AppleScript access
3. The server will validate Things3 availability before operations
## Architecture
### Components
- **`server.py`**: Main MCP server implementation with tool definitions and handlers
- **`applescript_handler.py`**: AppleScript integration with JSON serialization via Foundation framework
- **`applescript/`**: Dedicated AppleScript files for each bulk operation using JSON output
- **URL Encoding**: Proper x-callback-url parameter encoding for special characters
- **Error Handling**: Comprehensive validation and graceful error recovery
### Key Features
- **JSON Serialization**: Uses macOS Foundation framework for reliable data extraction
- **ID-Based Operations**: All tasks tracked by unique IDs, not titles
- **Auth Token Support**: Environment variable for Things3 URL scheme authentication
- **Philosophy Integration**: Built-in guidance for effective Things3 usage
- **Bulk Operations**: Efficient retrieval of multiple items with proper JSON structure
## Development
### Testing
The server includes comprehensive logging for debugging. Individual tools can be tested through the MCP protocol once configured with your client.
### Debugging
The server includes comprehensive logging. Set log level for debugging:
```bash
export PYTHONPATH="."
python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from src.mcp_server_things3.server import main
import asyncio
asyncio.run(main())
"
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## Troubleshooting
### Common Issues
**"Things3 is not available"**
- Ensure Things3 is installed and running
- Grant AppleScript permissions when prompted
- Check Things3 is not in a permission-restricted mode
**"Failed to execute AppleScript"**
- Verify macOS security settings allow AppleScript
- Ensure Things3 has necessary accessibility permissions
- Try restarting Things3
**URL encoding issues with special characters**
- The server now properly handles unicode and special characters
- If issues persist, check the logs for specific URL construction errors
**"Authentication Required" for update operations**
- Ensure THINGS3_AUTH_TOKEN environment variable is set
- Get token from Things3 Settings → General → Enable Things URLs → Manage
- Each device has its own unique token
### Performance Notes
- AppleScript operations may have slight delays
- Large todo lists (1000+ items) may take longer to search
- Consider using specific searches rather than broad queries for better performance
## License
MIT License - see LICENSE file for details.
## Changelog
### v0.2.0
- Added `update-things3-todo` tool with auth token support
- Added `view-upcoming` and `view-anytime` tools
- Implemented JSON serialization using Foundation framework
- Changed to ID-based operations (no more title searching)
- Added Today overload warnings (>4 items)
- Added Things3 philosophy guidance in tool descriptions
- Updated Python requirement to 3.10+
- All responses now include task/project IDs
### v0.1.0
- Initial release with basic CRUD operations
- Comprehensive error handling and validation
- Secure URL encoding and AppleScript integration
- Search and completion functionality
Raw data
{
"_id": null,
"home_page": null,
"name": "things3-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "claude, macos, mcp, task-management, things3",
"author": null,
"author_email": "Darin Kishore <darin@darinkishore.com>",
"download_url": "https://files.pythonhosted.org/packages/66/9c/88ded6df172b4543646555c80db3f458c8d158fbfa732f34850fa0fd41e5/things3_mcp-0.2.0.tar.gz",
"platform": null,
"description": "# MCP Server for Things3\n\nA robust MCP (Model Context Protocol) server providing comprehensive integration with Things3, allowing you to create, manage, and search tasks and projects through the MCP protocol. Features ID-based task management, JSON-based AppleScript integration, and Things3 philosophy guidance.\n\n## Features\n\n- \u2705 **Create Projects & Todos**: Full metadata support with checklists, tags, and dates\n- \u2705 **Update Tasks**: Modify any task property using task IDs with auth token support\n- \u2705 **View Tasks**: List tasks from Inbox, Today, Upcoming, Anytime, or Projects\n- \u2705 **Complete Tasks**: Mark todos as completed using their ID\n- \u2705 **Search Functionality**: Search through all todos by title or content\n- \u2705 **Things3 Philosophy**: Built-in guidance for effective task management\n- \u2705 **JSON Integration**: Reliable data extraction using Foundation framework\n- \u2705 **Today Overload Warning**: Alerts when Today list exceeds 4 items\n\n## Installation\n\n### Prerequisites\n- macOS with Things3 installed\n- Python 3.10+ \n- Things3 running (for real-time operations)\n- Things3 auth token (for update operations)\n\n### Install the Server\n\n1. Clone this repository:\n ```bash\n git clone <repository-url>\n cd mcp-things3\n ```\n\n2. Install using pip:\n ```bash\n pip install -e .\n ```\n\n3. The server will be available as `mcp-server-things3`\n\n### Auth Token Setup\n\nFor update operations, you need to set your Things3 auth token:\n\n1. Open Things3\n2. Go to Settings \u2192 General \u2192 Enable Things URLs \u2192 Manage\n3. Copy your auth token\n4. Set the environment variable:\n ```bash\n export THINGS3_AUTH_TOKEN=\"your-token-here\"\n ```\n\n## Tools Available\n\n### View Operations\n\n#### `view-inbox`\nView all todos in the Things3 inbox.\n- **Parameters**: None\n- **Returns**: List of inbox todos with IDs, titles, tags, and metadata\n\n#### `view-todos`\nView all todos in today's list with overload warning.\n- **Parameters**: None\n- **Returns**: List of today's todos with IDs and warning if >4 items\n\n#### `view-upcoming`\nView scheduled future tasks in Things3's Upcoming list.\n- **Parameters**: None\n- **Returns**: Tasks organized by date, showing what's hibernating until scheduled\n\n#### `view-anytime`\nView all unscheduled active tasks in Things3's Anytime list.\n- **Parameters**: None\n- **Returns**: Tasks organized by project/area, ready whenever you are\n\n#### `view-projects`\nView all projects in Things3.\n- **Parameters**: None \n- **Returns**: List of all projects with IDs and titles\n\n### Creation Operations\n\n#### `create-things3-project`\nCreates a new project in Things3.\n- **Required**: `title` (string)\n- **Optional**: \n - `notes` (string)\n - `area` (string) \n - `when` (string) - Date/time to start\n - `deadline` (string) - Due date\n - `tags` (array of strings)\n\n**Example**:\n```json\n{\n \"title\": \"Website Redesign\",\n \"notes\": \"Complete overhaul of company website\",\n \"area\": \"Work\",\n \"deadline\": \"2024-03-15\",\n \"tags\": [\"urgent\", \"web-dev\"]\n}\n```\n\n#### `create-things3-todo`\nCreates a new to-do in Things3.\n- **Required**: `title` (string)\n- **Optional**:\n - `notes` (string)\n - `when` (string) - Date/time to start \n - `deadline` (string) - Due date\n - `checklist` (array of strings)\n - `tags` (array of strings)\n - `list` (string) - Project or area to assign to\n - `heading` (string) - Group under this heading\n\n**Example**:\n```json\n{\n \"title\": \"Review design mockups\",\n \"notes\": \"Check the new homepage designs\",\n \"list\": \"Website Redesign\", \n \"deadline\": \"2024-02-20\",\n \"tags\": [\"review\"],\n \"checklist\": [\"Check mobile responsiveness\", \"Verify brand guidelines\", \"Test accessibility\"]\n}\n```\n\n### Management Operations\n\n#### `update-things3-todo`\nUpdate an existing to-do in Things3. Requires auth token.\n- **Required**: `id` (string) - Todo ID from view/search results\n- **Optional**: All todo fields (title, notes, when, deadline, tags, etc.)\n- **Special**: `completed`, `canceled` (boolean) for status changes\n- **Returns**: Success message with philosophical guidance\n\n**Example**:\n```json\n{\n \"id\": \"2DCAbD81QBc6oQbzaNjFhM\",\n \"when\": \"tomorrow\",\n \"tags\": [\"urgent\", \"review\"]\n}\n```\n\n#### `complete-things3-todo`\nMark a todo as completed using its ID.\n- **Required**: `id` (string) - Todo ID from view/search results\n- **Returns**: Success/failure message\n\n**Example**:\n```json\n{\n \"id\": \"2DCAbD81QBc6oQbzaNjFhM\"\n}\n```\n\n#### `search-things3-todos`\nSearch for todos by title or content.\n- **Required**: `query` (string) - Search term\n- **Returns**: List of matching todos with status and metadata\n\n**Example**:\n```json\n{\n \"query\": \"website\"\n}\n```\n\n## Integration with Claude\n\nThis MCP server is designed to work seamlessly with Claude AI. Once configured, you can use natural language to manage your Things3 tasks:\n\n- \"Create a project called 'Q1 Planning' with a deadline of March 31st\"\n- \"Add a todo to review the budget with a checklist of tasks\"\n- \"Show me all my tasks for today\"\n- \"Mark the 'Call client' task as completed\"\n- \"Search for all todos related to the website project\"\n\n## Configuration\n\n### MCP Client Configuration\n\nAdd to your MCP client configuration (e.g., Claude Desktop config):\n\n```json\n{\n \"mcpServers\": {\n \"things3\": {\n \"command\": \"mcp-server-things3\",\n \"args\": []\n }\n }\n}\n```\n\n### Things3 Setup\n\n1. Ensure Things3 is installed and running\n2. Grant necessary permissions when prompted for AppleScript access\n3. The server will validate Things3 availability before operations\n\n## Architecture\n\n### Components\n\n- **`server.py`**: Main MCP server implementation with tool definitions and handlers\n- **`applescript_handler.py`**: AppleScript integration with JSON serialization via Foundation framework\n- **`applescript/`**: Dedicated AppleScript files for each bulk operation using JSON output\n- **URL Encoding**: Proper x-callback-url parameter encoding for special characters\n- **Error Handling**: Comprehensive validation and graceful error recovery\n\n### Key Features\n\n- **JSON Serialization**: Uses macOS Foundation framework for reliable data extraction\n- **ID-Based Operations**: All tasks tracked by unique IDs, not titles\n- **Auth Token Support**: Environment variable for Things3 URL scheme authentication\n- **Philosophy Integration**: Built-in guidance for effective Things3 usage\n- **Bulk Operations**: Efficient retrieval of multiple items with proper JSON structure\n\n## Development\n\n### Testing\n\nThe server includes comprehensive logging for debugging. Individual tools can be tested through the MCP protocol once configured with your client.\n\n### Debugging\n\nThe server includes comprehensive logging. Set log level for debugging:\n\n```bash\nexport PYTHONPATH=\".\"\npython -c \"\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\nfrom src.mcp_server_things3.server import main\nimport asyncio\nasyncio.run(main())\n\"\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Things3 is not available\"**\n- Ensure Things3 is installed and running\n- Grant AppleScript permissions when prompted\n- Check Things3 is not in a permission-restricted mode\n\n**\"Failed to execute AppleScript\"**\n- Verify macOS security settings allow AppleScript\n- Ensure Things3 has necessary accessibility permissions\n- Try restarting Things3\n\n**URL encoding issues with special characters**\n- The server now properly handles unicode and special characters\n- If issues persist, check the logs for specific URL construction errors\n\n**\"Authentication Required\" for update operations**\n- Ensure THINGS3_AUTH_TOKEN environment variable is set\n- Get token from Things3 Settings \u2192 General \u2192 Enable Things URLs \u2192 Manage\n- Each device has its own unique token\n\n### Performance Notes\n\n- AppleScript operations may have slight delays\n- Large todo lists (1000+ items) may take longer to search\n- Consider using specific searches rather than broad queries for better performance\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Changelog\n\n### v0.2.0\n- Added `update-things3-todo` tool with auth token support\n- Added `view-upcoming` and `view-anytime` tools\n- Implemented JSON serialization using Foundation framework\n- Changed to ID-based operations (no more title searching)\n- Added Today overload warnings (>4 items)\n- Added Things3 philosophy guidance in tool descriptions\n- Updated Python requirement to 3.10+\n- All responses now include task/project IDs\n\n### v0.1.0\n- Initial release with basic CRUD operations\n- Comprehensive error handling and validation\n- Secure URL encoding and AppleScript integration\n- Search and completion functionality\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A server implementation for interacting with Things3 app on macOS through Claude AI",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/darinkishore/mcp-things3",
"Issues": "https://github.com/darinkishore/mcp-things3/issues",
"Repository": "https://github.com/darinkishore/mcp-things3"
},
"split_keywords": [
"claude",
" macos",
" mcp",
" task-management",
" things3"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f73785124e6a9df81d367468a792ebff3fedcc26edb677cce143b98c3a0fd0c1",
"md5": "fda6642b69b3145372d52facdc99df3c",
"sha256": "add7d42f148d72cbbac5d82485494998e6ad0643d1628339d7fddcdb8c50ca83"
},
"downloads": -1,
"filename": "things3_mcp-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fda6642b69b3145372d52facdc99df3c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 17944,
"upload_time": "2025-07-21T21:26:45",
"upload_time_iso_8601": "2025-07-21T21:26:45.044480Z",
"url": "https://files.pythonhosted.org/packages/f7/37/85124e6a9df81d367468a792ebff3fedcc26edb677cce143b98c3a0fd0c1/things3_mcp-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "669c88ded6df172b4543646555c80db3f458c8d158fbfa732f34850fa0fd41e5",
"md5": "f2f70c3425275dee77bee4c4a4656b57",
"sha256": "2b5b92cac4ada8e092b9b1b8e75746ad2f4214e2c2dfbaeec0950fad973cba77"
},
"downloads": -1,
"filename": "things3_mcp-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "f2f70c3425275dee77bee4c4a4656b57",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 71365,
"upload_time": "2025-07-21T21:26:47",
"upload_time_iso_8601": "2025-07-21T21:26:47.633410Z",
"url": "https://files.pythonhosted.org/packages/66/9c/88ded6df172b4543646555c80db3f458c8d158fbfa732f34850fa0fd41e5/things3_mcp-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-21 21:26:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "darinkishore",
"github_project": "mcp-things3",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "things3-mcp"
}
