# Things MCP
A Model Context Protocol (MCP) server for Things 3 integration. Enables Claude Desktop and Claude Code to interact with Things 3 on macOS.
## Features
- Create to-dos and projects with full metadata
- Update existing to-dos and projects
- List items from any Things list (Inbox, Today, Logbook, Trash, etc.)
- Retrieve all projects, areas, and tags
- Navigate to specific items or lists
- Search within Things
- Secure AppleScript execution
- Comprehensive error handling
## Requirements
- macOS with Things 3 installed
- Node.js 18 or later
- Things URL scheme enabled (automatic on first use)
## Installation
### Quick Start with npx (Recommended)
```bash
npx github:hildersantos/things-mcp
```
This will automatically download, build, and start the MCP server.
### Manual Installation
1. Clone this repository:
```bash
git clone https://github.com/hildersantos/things-mcp.git
cd things-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
4. Start the server:
```bash
npm start
```
## Configuration
### Claude Desktop Setup
1. **Get your Things auth token** (required for update operations):
- Open Things → Settings → General
- Enable Things URLs
- Click Manage → Copy Token
2. **Configure Claude Desktop**:
Open your Claude Desktop configuration file:
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```
Add the Things MCP server to the `mcpServers` section:
```json
{
"mcpServers": {
"things-mcp": {
"command": "npx",
"args": ["github:hildersantos/things-mcp"],
"env": {
"THINGS_AUTH_TOKEN": "your-token-here"
}
}
}
}
```
Replace `your-token-here` with your actual Things auth token from step 1.
3. **Restart Claude Desktop** to apply the configuration changes.
### Alternative: Local Installation
If you prefer to install locally instead of using npx:
```json
{
"mcpServers": {
"things-mcp": {
"command": "node",
"args": ["/absolute/path/to/things-mcp/dist/index.js"],
"env": {
"THINGS_AUTH_TOKEN": "your-token-here"
}
}
}
}
```
## Usage Examples
### Create a To-Do
```
Create a task "Buy milk" for today with tag "errands" in Things
```
### Create a Simple Project
```
Create a "Website Redesign" project in Things in my Work area
```
### Create a Complex Project
```
Plan a vacation to Japan in Things with research about destinations, booking flights and hotels,
creating a packing list, and planning daily activities
```
### Another Project Example
```
Set up a new employee onboarding project in Things with IT setup tasks, HR paperwork,
training schedule, and first week activities
```
### Update a To-Do
```
Mark task ABC-123 as completed in Things
```
### Add Items to Existing Project
```
Add new tasks to my "Website Redesign" project in Things: create wireframes, design mockups, and user testing
```
### List Tasks
```
Show me all tasks in my Things inbox
```
### View Projects
```
List all my projects in Things
```
### Navigate
```
Open my Today list in Things
```
### Get Task Details
```
Get full details for task TBeaUrcGH1zKoMmS7wwHVD from Things
```
### Search
```
Search for "meeting" in Things
```
### View Completed Tasks
```
Show me my completed tasks from the Things logbook
```
## Available Tools
### Creation Tools
- `things_add_todo` - Create a to-do with all options
- `things_add_project` - Create a project with sections (headings), todos, and hierarchical organization
### Update Tools (requires auth token)
- `things_update_todo` - Update an existing to-do using JSON API for full feature support
- `things_update_project` - Update an existing project using JSON API for full feature support
- `things_add_items_to_project` - Add structured todos and headings to an existing project
### Reading Tools
- `things_get_inbox` - List inbox items
- `things_get_today` - List today's items
- `things_get_upcoming` - List scheduled items
- `things_get_anytime` - List anytime items
- `things_get_someday` - List someday items
- `things_get_logbook` - List completed items
- `things_get_trash` - List trashed items
- `things_get_projects` - List all active projects
- `things_get_areas` - List all areas
- `things_get_tags` - List all tags
- `things_get_project` - List items in a specific project (requires project_id)
- `things_get_area` - List items in a specific area (requires area_id)
- `things_get_list` - Get items from a specific list by name
- `things_get_todo_details` - Get detailed information about a specific to-do
All list tools support an optional `max_results` parameter to limit output.
### Navigation Tools
- `things_show` - Navigate to item or list
## Development
```bash
# Development mode with watch
npm run dev
# Run linter
npm run lint
# Format code
npm run format
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
```
## Troubleshooting
### "Things 3 does not appear to be running"
Make sure Things 3 is installed and has been opened at least once.
### "Authentication failed"
Check that your THINGS_AUTH_TOKEN is correctly set in the MCP configuration.
### AppleScript Permissions
On first run, macOS may ask for permission to control Things. Grant this permission for the MCP to work.
### Performance Issues
Use the `max_results` parameter when listing large collections:
```
Use things_get_projects with max_results 10
```
## License
MIT
## Credits
Built with the [Model Context Protocol SDK](https://github.com/anthropics/mcp).
Things is a trademark of Cultured Code GmbH & Co. KG.
