{"_id":"things3-mcp","_rev":"2-7a5f4fbeee08ae10dee208b43e0e40e5","name":"things3-mcp","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"things3-mcp","version":"0.1.0","keywords":["mcp","things3","macos","task-management","applescript","model-context-protocol","productivity"],"author":"","license":"MIT","_id":"things3-mcp@0.1.0","maintainers":[{"name":"urbanogardun","email":"urbanogardun@gmail.com"}],"homepage":"https://github.com/urbanogardun/things3-mcp#readme","bugs":{"url":"https://github.com/urbanogardun/things3-mcp/issues"},"bin":{"things3-mcp":"dist/index.js"},"dist":{"shasum":"02cac80bf6641f4d76cd1c351794eab281f5c8f0","tarball":"https://registry.npmjs.org/things3-mcp/-/things3-mcp-0.1.0.tgz","fileCount":107,"integrity":"sha512-px/OfLIunavH477KEJFi9Aec7uOw2WE6AkxsAc6gVixoV3dP3X8PGSPOb/t7/Q1ee+PU2EwKiRYdF81u4/uAVA==","signatures":[{"sig":"MEQCIByJZe5nue2HtAioQ7fEKA08Xyp/csllPL2uzXTqAMsBAiA/GLKBqo7cA4XCSQ/tzL1WZjGceu5vmtQDkBVB4mAI1w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/things3-mcp@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":376538},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=16.0.0"},"gitHead":"ee88bce992760f60389eff8cfb5f54e08b6210dd","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .ts","test":"npm run test:unit","build":"tsc && chmod +x dist/index.js","start":"node dist/index.js","format":"prettier --write \"src/**/*.ts\"","prepare":"husky install","test:all":"npm run test:unit && npm run test:integration","test:unit":"jest --testPathPattern=unit","type-check":"tsc --noEmit","prepublishOnly":"npm run build","test:integration":"jest --config jest.config.integration.js"},"_npmUser":{"name":"urbanogardun","email":"urbanogardun@gmail.com"},"repository":{"url":"git+https://github.com/urbanogardun/things3-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server for Things3 integration on macOS","directories":{},"_nodeVersion":"20.19.2","dependencies":{"zod":"^3.22.0","dotenv":"^16.5.0","@types/dotenv":"^6.1.1","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.5.0","husky":"^8.0.0","eslint":"^8.0.0","ts-jest":"^29.1.0","prettier":"^3.0.0","typescript":"^5.0.0","@types/jest":"^29.5.0","@types/node":"^20.0.0","eslint-config-prettier":"^9.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/things3-mcp_0.1.0_1748523786247_0.2900039501569516","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"things3-mcp","version":"0.2.0","description":"MCP server for Things3 integration on macOS","main":"dist/index.js","type":"module","bin":{"things3-mcp":"dist/index.js"},"repository":{"type":"git","url":"git+https://github.com/urbanogardun/things3-mcp.git"},"homepage":"https://github.com/urbanogardun/things3-mcp#readme","bugs":{"url":"https://github.com/urbanogardun/things3-mcp/issues"},"scripts":{"build":"tsc && chmod +x dist/index.js","dev":"tsc --watch","start":"node dist/index.js","lint":"eslint src --ext .ts","type-check":"tsc --noEmit","format":"prettier --write \"src/**/*.ts\"","test":"npm run test:unit","test:unit":"jest --testPathPattern=unit","test:integration":"jest --config jest.config.integration.js","test:all":"npm run test:unit && npm run test:integration","prepare":"husky install","prepublishOnly":"npm run build"},"keywords":["mcp","things3","macos","task-management","applescript","model-context-protocol","productivity"],"author":"","license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","@types/dotenv":"^6.1.1","dotenv":"^16.5.0","zod":"^3.22.0"},"devDependencies":{"@types/jest":"^29.5.0","@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","eslint-config-prettier":"^9.0.0","husky":"^8.0.0","jest":"^29.5.0","prettier":"^3.0.0","ts-jest":"^29.1.0","typescript":"^5.0.0"},"engines":{"node":">=16.0.0"},"_id":"things3-mcp@0.2.0","gitHead":"743690266cd472efa4cd595d50914863a8be6476","types":"./dist/index.d.ts","_nodeVersion":"20.19.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-j9fz1Ne4XhjU4ouk7QbucnF70R8c02hYGj/7lqocdPLZ+q8v1m1oBq3OCzgkiORwVEA5j4rEWnChusRgxtD7Lg==","shasum":"a254b9b45f3e479c80bf61a3e8084eccabe9d152","tarball":"https://registry.npmjs.org/things3-mcp/-/things3-mcp-0.2.0.tgz","fileCount":99,"unpackedSize":411092,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/things3-mcp@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDtltskW3l1U+qvu6XtVwlqB3J2C5damwqdaZRMdH9XkQIhAIDZh9pze79GgwakZpjZa5o/X6iyMOK4ryrmEujKhbDv"}]},"_npmUser":{"name":"urbanogardun","email":"urbanogardun@gmail.com"},"directories":{},"maintainers":[{"name":"urbanogardun","email":"urbanogardun@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/things3-mcp_0.2.0_1749031483792_0.04846534063942132"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-29T13:03:06.145Z","modified":"2025-06-04T10:04:44.416Z","0.1.0":"2025-05-29T13:03:06.485Z","0.2.0":"2025-06-04T10:04:44.016Z"},"bugs":{"url":"https://github.com/urbanogardun/things3-mcp/issues"},"license":"MIT","homepage":"https://github.com/urbanogardun/things3-mcp#readme","keywords":["mcp","things3","macos","task-management","applescript","model-context-protocol","productivity"],"repository":{"type":"git","url":"git+https://github.com/urbanogardun/things3-mcp.git"},"description":"MCP server for Things3 integration on macOS","maintainers":[{"name":"urbanogardun","email":"urbanogardun@gmail.com"}],"readme":"# Things3 MCP Server\n\n[![Test](https://github.com/urbanogardun/things3-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/urbanogardun/things3-mcp/actions/workflows/test.yml)\n[![npm version](https://badge.fury.io/js/things3-mcp.svg)](https://badge.fury.io/js/things3-mcp)\n\nAn MCP (Model Context Protocol) server that provides comprehensive integration with Things3 on macOS. This server enables AI assistants and other MCP clients to interact with Things3 through 25 specialized tools, offering complete task management capabilities with intelligent error correction and automatic tag creation.\n\n## Features\n\n- **Complete Things3 Integration**: 25 tools covering all aspects of Things3\n- **TODO Management**: Create, read, update, delete, complete, and uncomplete tasks\n- **Project & Area Management**: Full project lifecycle support with area organization and deletion\n- **Tag System**: Hierarchical tag support with creation, deletion, and bulk tag operations\n- **Bulk Operations**: Efficiently move or update multiple items at once\n- **Automatic Tag Creation**: Tags are automatically created when referenced in TODO/project operations\n- **Error Correction**: Automatic fixing of common issues (date conflicts, missing titles)\n- **Logbook Search**: Search completed items with date range filtering\n- **Performance Optimized**: Connection pooling and AppleScript optimization\n\n## Requirements\n\n- **macOS** (Things3 is macOS-only)\n- **Node.js** >= 16.0.0\n- **Things3** app installed\n- **AppleScript** access enabled in System Settings\n\n## Installation\n\n### Quick Start (Recommended)\n\nOnce published to npm, you can use the server without any installation:\n\n```json\n{\n  \"mcpServers\": {\n    \"things3\": {\n      \"command\": \"npx\",\n      \"args\": [\"things3-mcp@latest\"]\n    }\n  }\n}\n```\n\n### Install from npm\n\n```bash\nnpm install -g things3-mcp\n```\n\nThen add to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"things3\": {\n      \"command\": \"things3-mcp\"\n    }\n  }\n}\n```\n\n### Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/urbanogardun/things3-mcp.git\ncd things3-mcp\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n## Configuration\n\n### Environment Variables\n\nFor update operations (modify, complete, delete), you need to set your Things3 authorization token:\n\n```bash\nexport THINGS3_AUTH_TOKEN=\"your_auth_token_here\"\n```\n\nTo find your authorization token:\n1. Open Things3\n2. Go to Settings → General\n3. Look for \"Authorization Token\" section\n4. Copy the token value\n\nYou can also create a `.env` file (see `.env.example`).\n\n### For Claude Desktop\n\n1. Open Claude Desktop configuration:\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n2. Add the Things3 MCP server using one of these methods:\n\n   **Method 1: Using npx (easiest, no installation required)**\n   ```json\n   {\n     \"mcpServers\": {\n       \"things3\": {\n         \"command\": \"npx\",\n         \"args\": [\"things3-mcp@latest\"],\n         \"env\": {\n           \"THINGS3_AUTH_TOKEN\": \"your_auth_token_here\"\n         }\n       }\n     }\n   }\n   ```\n\n   **Method 2: Global npm install**\n   ```json\n   {\n     \"mcpServers\": {\n       \"things3\": {\n         \"command\": \"things3-mcp\",\n         \"env\": {\n           \"THINGS3_AUTH_TOKEN\": \"your_auth_token_here\"\n         }\n     }\n   }\n   ```\n\n   **Method 3: Local installation**\n   ```json\n   {\n     \"mcpServers\": {\n       \"things3\": {\n         \"command\": \"node\",\n         \"args\": [\"/absolute/path/to/things3-mcp/dist/index.js\"]\n       }\n     }\n   }\n   ```\n\n3. Restart Claude Desktop\n\n### For Other MCP Clients\n\nUse any of the methods above, adapting the configuration to your MCP client's format.\n\n## Available Tools\n\n### TODO Tools (7)\n\n#### `todos_list`\nList TODOs with flexible filtering options.\n\n**Parameters:**\n- `filter`: `\"inbox\"` | `\"today\"` | `\"upcoming\"` | `\"anytime\"` | `\"someday\"` | `\"logbook\"` (optional)\n- `searchText`: Search within titles and notes (optional)\n\n**Example:**\n```json\n{\n  \"filter\": \"today\",\n  \"searchText\": \"meeting\"\n}\n```\n\n#### `todos_get`\nGet detailed information about a specific TODO.\n\n**Parameters:**\n- `id`: The TODO's unique identifier (required)\n\n#### `todos_create`\nCreate a new TODO with full property support (automatically creates tags if they don't exist).\n\n**Parameters:**\n- `title`: Task title (required)\n- `notes`: Additional notes (optional)\n- `whenDate`: ISO 8601 date string for scheduling (optional)\n- `deadline`: ISO 8601 date string for due date (optional)\n- `tags`: Array of tag names (optional)\n- `checklistItems`: Array of checklist item titles (optional) *\n- `projectId`: Assign to project (optional)\n- `areaId`: Assign to area (optional)\n- `heading`: Title of heading within project to add to (optional)\n\n**Example:**\n```json\n{\n  \"title\": \"Review Q4 Report\",\n  \"notes\": \"Focus on revenue metrics\",\n  \"whenDate\": \"2024-12-15T09:00:00Z\",\n  \"deadline\": \"2024-12-20T17:00:00Z\",\n  \"tags\": [\"work\", \"urgent\"],\n  \"checklistItems\": [\"Review revenue\", \"Check expenses\", \"Update forecast\"],\n  \"projectId\": \"project-id-here\"\n}\n```\n\n\\* **Note on Checklists**: When `checklistItems` are provided, the TODO is created using Things3's URL scheme instead of AppleScript. This approach has some limitations:\n- Things3 may briefly come to the foreground\n- The created TODO's ID cannot be directly retrieved, so the server searches for it by title\n- If multiple TODOs have identical titles, the wrong TODO might be returned\n- URL scheme support must be enabled in Things3 settings (Settings → General → Enable Things URLs)\n\n#### `todos_update`\nUpdate an existing TODO's properties (automatically creates tags if they don't exist).\n\n**Parameters:**\n- `id`: TODO identifier (required)\n- All parameters from `todos_create` (optional)\n\n#### `todos_complete`\nMark one or more TODOs as complete.\n\n**Parameters:**\n- `ids`: Single ID or array of IDs (required)\n\n#### `todos_uncomplete`\nMark one or more TODOs as incomplete.\n\n**Parameters:**\n- `ids`: Single ID or array of IDs (required)\n\n#### `todos_delete`\nDelete one or more TODOs permanently.\n\n**Parameters:**\n- `ids`: Single ID or array of IDs (required)\n\n### Project Tools (6)\n\n#### `projects_list`\nList projects with optional filtering.\n\n**Parameters:**\n- `areaId`: Filter by area (optional)\n- `includeCompleted`: Include completed projects (optional, default: false)\n\n#### `projects_get`\nGet detailed project information.\n\n**Parameters:**\n- `id`: Project identifier (required)\n\n#### `projects_create`\nCreate a new project (automatically creates tags if they don't exist).\n\n**Parameters:**\n- `name`: Project name (required)\n- `notes`: Project description (optional)\n- `areaId`: Assign to area (optional)\n- `whenDate`: Start date (optional)\n- `deadline`: Due date (optional)\n- `tags`: Array of tag names (optional)\n- `headings`: Array of section headings (optional)\n\n#### `projects_update`\nUpdate project properties (automatically creates tags if they don't exist).\n\n**Parameters:**\n- `id`: Project identifier (required)\n- All parameters from `projects_create` except `headings` (optional)\n\n#### `projects_complete`\nMark a project as complete.\n\n**Parameters:**\n- `id`: Project identifier (required)\n\n#### `projects_delete`\nDelete projects completely from Things3.\n\n**Parameters:**\n- `ids`: Single project ID or array of project IDs (required)\n\n### Area Tools (3)\n\n#### `areas_list`\nList all areas.\n\n**Parameters:**\n- `includeHidden`: Include hidden areas (optional, default: false)\n\n#### `areas_create`\nCreate a new area.\n\n**Parameters:**\n- `name`: Area name (required)\n\n#### `areas_delete`\nDelete areas completely from Things3.\n\n**Parameters:**\n- `ids`: Single area ID or array of area IDs (required)\n\n### Tag Tools (5)\n\n#### `tags_list`\nList all tags with hierarchy information.\n\n**Returns:** Array of tags with `parentTagId` for nested tags\n\n#### `tags_create`\nCreate a new tag.\n\n**Parameters:**\n- `name`: Tag name (required)\n- `parentTagId`: Parent tag for nesting (optional)\n\n#### `tags_add`\nAdd tags to items (automatically creates tags if they don't exist).\n\n**Parameters:**\n- `itemIds`: Single ID or array of TODO/Project IDs (required)\n- `tags`: Array of tag names to add (required)\n\n#### `tags_remove`\nRemove tags from items.\n\n**Parameters:**\n- `itemIds`: Single ID or array of TODO/Project IDs (required)\n- `tags`: Array of tag names to remove (required)\n\n#### `tags_delete`\nDelete tags completely from Things3.\n\n**Parameters:**\n- `names`: Single tag name or array of tag names (required)\n\n### Bulk Tools (2)\n\n#### `bulk_move`\nMove multiple TODOs to a project or area.\n\n**Parameters:**\n- `todoIds`: Array of TODO IDs (required)\n- `projectId`: Target project (optional)\n- `areaId`: Target area (optional)\n\n#### `bulk_updateDates`\nUpdate dates for multiple TODOs.\n\n**Parameters:**\n- `todoIds`: Array of TODO IDs (required)\n- `whenDate`: New scheduled date or null to clear (optional)\n- `deadline`: New deadline or null to clear (optional)\n\n### Logbook Tool (1)\n\n#### `logbook_search`\nSearch completed items in the logbook.\n\n**Parameters:**\n- `searchText`: Search in titles and notes (optional)\n- `fromDate`: Start date for range (optional)\n- `toDate`: End date for range (optional)\n- `limit`: Maximum results (optional, default: 50)\n\n### System Tools (1)\n\n#### `system_launch`\nEnsure Things3 is running and ready.\n\n## Error Correction\n\nThe server automatically corrects common issues:\n\n- **Date Conflicts**: Swaps when/deadline if deadline is before scheduled date\n- **Missing Titles**: Generates title from notes or uses \"Untitled\"\n- **Invalid References**: Moves items to Inbox if project/area doesn't exist\n- **Tag Names**: Cleans special characters that Things3 doesn't support\n\n## Usage Examples\n\n### With Claude Desktop\n\n```\nHuman: Create a new project for the website redesign with tasks for planning, design, and implementation\n\nClaude: I'll create a website redesign project with those tasks for you.\n\n[Creates project and tasks using the Things3 MCP tools]\n```\n\n### Direct Tool Usage\n\nCreate a TODO:\n```json\n{\n  \"tool\": \"todos_create\",\n  \"parameters\": {\n    \"title\": \"Prepare presentation\",\n    \"notes\": \"Include Q4 metrics and projections\",\n    \"whenDate\": \"2024-12-10T14:00:00Z\",\n    \"tags\": [\"work\", \"presentation\"]\n  }\n}\n```\n\nList today's tasks:\n```json\n{\n  \"tool\": \"todos_list\",\n  \"parameters\": {\n    \"filter\": \"today\"\n  }\n}\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Install dependencies\nnpm install\n\n# Run in development mode with watch\nnpm run dev\n\n# Run tests\nnpm test\n\n# Run integration tests (requires Things3)\nnpm run test:integration\n\n# Lint code\nnpm run lint\n\n# Type check\nnpm run type-check\n```\n\n### Project Structure\n\n```\nthings3-mcp/\n├── src/\n│   ├── index.ts          # Entry point\n│   ├── server.ts         # MCP server implementation\n│   ├── config.ts         # Configuration management\n│   ├── tools/            # Tool implementations\n│   │   ├── todos.ts      # TODO operations\n│   │   ├── projects.ts   # Project operations\n│   │   ├── areas.ts      # Area operations\n│   │   ├── tags.ts       # Tag operations\n│   │   ├── bulk.ts       # Bulk operations\n│   │   ├── logbook.ts    # Logbook search\n│   │   └── system.ts     # System utilities\n│   ├── templates/        # AppleScript templates\n│   ├── utils/            # Utility functions\n│   │   ├── applescript.ts     # AppleScript bridge\n│   │   ├── cache-manager.ts   # Caching system\n│   │   ├── error-correction.ts # Error correction\n│   │   └── date-handler.ts    # Date formatting\n│   └── types/            # TypeScript definitions\n├── tests/\n│   ├── unit/            # Unit tests\n│   └── integration/     # Integration tests\n└── dist/                # Compiled JavaScript\n```\n\n## Troubleshooting\n\n### Things3 Not Responding\n1. Ensure Things3 is installed and running\n2. Check AppleScript permissions in System Settings > Privacy & Security > Privacy > Automation\n3. Grant your terminal or IDE permission to control Things3\n\n### Permission Errors\n- macOS may require you to grant automation permissions\n- Run this command to test AppleScript access:\n  ```bash\n  osascript -e 'tell application \"Things3\" to return name of first to do'\n  ```\n\n### MCP Connection Issues\n1. Verify the path in your configuration is absolute\n2. Check that the server builds successfully: `npm run build`\n3. Look for error messages in your MCP client's logs\n4. Try running the server directly: `node dist/index.js`\n\n### Date Format Issues\n- Dates must be in ISO 8601 format (e.g., \"2024-12-25T10:00:00Z\")\n- The server automatically handles timezone conversion\n- If dates appear incorrect, check your system's date format settings\n\n### Performance Issues\n- For large operations, use bulk tools instead of individual operations\n- Tag operations automatically create missing tags, which may slow down initial operations\n\n## Known Limitations\n\n1. **Checklist Items**: \n   - Things3's AppleScript API doesn't support checklist manipulation\n   - We use URL schemes as a workaround when creating TODOs with checklists\n   - This may cause Things3 to briefly come to the foreground\n   - Existing checklist items cannot be modified after creation\n2. **Deleted Items Recovery**: Deleted items cannot be recovered via the API\n3. **Reminder Details**: Limited reminder information available through AppleScript\n4. **Tag Hierarchy**: Tag parent-child relationships are read-only (but tags can be created and deleted)\n5. **URL Scheme Limitations**: \n   - When using URL schemes (for checklists), the newly created TODO's ID cannot be directly retrieved\n   - The server performs a search to find the created TODO, which may fail if multiple TODOs have identical titles\n\n## Contributing\n\nContributions are welcome! Please follow conventional commit format and ensure all tests pass before submitting pull requests.\n\n## Acknowledgments\n\n- Built with the [Model Context Protocol SDK](https://github.com/anthropics/mcp)\n- Integrates with [Things3](https://culturedcode.com/things/) by Cultured Code\n- Inspired by the MCP community and various automation tools\n","readmeFilename":"README.md"}