A comprehensive Claude Desktop Extension that provides seamless integration with Things 3, enabling you to manage your complete task workflow directly from Claude conversations using AppleScript via secure JavaScript for Automation (JXA).
- Install Dependencies:
npm install - Run Tests:
npm test(optional but recommended) - Package Extension:
mcpb pack . - Install in Claude Desktop: Follow Claude Desktop's extension installation process
- Launch Things 3: Ensure Things 3 is running before using commands
💡 Pro Tip: Use
whenfor scheduling (when to work on) anddeadlinefor final due dates.
- 📦 MCPB Format Migration: Updated from DXT to the new MCPB (MCP Bundle) format specification v0.2
- 📦 Package Updates: Updated @modelcontextprotocol/sdk to v1.20.1 and esbuild to v0.25.11
- 🔧 Tooling: Migrated from
dxtCLI tomcpbCLI for packaging - 📝 Documentation: Updated all documentation and references to reflect MCPB naming
- ✅ Compatibility: Maintained full backward compatibility with all existing functionality
- 🏗️ Complete Architecture Overhaul: Migrated from AppleScript to modular JavaScript for Automation (JXA)
- 🔒 Security-First Design: Eliminated shell injection risks with
execFileand JSON parameter passing - 📦 Modular Build System: ES6 modules compiled with esbuild for maintainable, modern code
- ⚡ Performance: Pre-built bundled scripts for faster execution
- 🧪 Comprehensive Testing: Unit, integration, and regression test suites
- 🔧 Better Error Handling: Enhanced error messages and timeout protection
- 📚 Developer Experience: Improved debugging, logging, and development workflow
- Complete Task Management: Create, read, update, and search todos and projects
- Smart List Access: Work with all Things 3 lists (Inbox, Today, Upcoming, Anytime, Someday)
- Project & Area Organization: Full project and area management capabilities
- Advanced Search: Multiple search types across all your Things data
- Tag Management: Get all tags and find items by specific tags
- Logbook Access: View completed tasks with flexible time periods
- Trash Management: Access and review trashed items
- Recent Items: Find recently modified items
- Flexible Updates: Modify existing tasks and projects with full parameter control
- Data Integrity: Comprehensive input validation and error handling
- Security: Built-in AppleScript injection protection and safe execution
- User-Friendly Parameters: Intuitive date terminology and parameter mapping
Required: title
Optional: notes, when, deadline, list_title, list_id, heading, tags, checklist_items
Required: title
Optional: notes, when, deadline, area_title, area_id, tags, todos
| Tool | Description | Parameters |
|---|---|---|
get_inbox |
Get todos from Inbox | None |
get_today |
Get todos due today | None |
get_upcoming |
Get upcoming todos | None |
get_anytime |
Get Anytime list todos | None |
get_someday |
Get Someday list todos | None |
get_logbook |
Get completed todos | period, limit |
get_trash |
Get trashed todos | None |
Optional: project_uuid, include_items
Optional: include_items
Optional: include_items
Required: query
Required: query
Required: query
Optional: tags, completed, canceled, trashed
Parameters: None
Required: tag_title
Optional: days (default: 7)
Required: id
Optional: title, notes, when, deadline, tags, checklist_items, completed, canceled
tags: Array of tag names. Use[]to remove all tagschecklist_items: Array of checklist items. Appends to existing notes as formatted list
Required: id
Optional: title, notes, when, deadline, tags, completed, canceled
tags: Array of tag names. Use[]to remove all tags
Required: id
Show me my inbox and today's tasks, then help me plan my day
Create a task "Prepare quarterly report" with notes "Include Q3 metrics and future roadmap" due next Friday in my Work project with tags "urgent" and "quarterly"
Create a new project "Website Redesign" in my "Product Development" area with deadline March 15th and add initial todos: "Research competitors", "Create wireframes", "Design mockups"
Search for all tasks containing "meeting" and show me what's tagged with "urgent"
Remove all tags from task ID "abc123" by updating it with tags: []
Show me what I completed last week, what's in my logbook, and help me organize my upcoming tasks
when: When scheduled to work on (appears in Today/Upcoming)deadline: When actually due (final deadline)- Format: YYYY-MM-DD (e.g., "2024-03-15")
list_title/area_title: Use names for easy referencelist_id/area_id: Use IDs for precise targetingtags: Array of tag names (e.g., ["urgent", "work"])
id: Required for all update operations- Status flags:
completed,canceled(boolean)
- macOS: Required for JXA integration
- Things 3: Must be installed and accessible
- Node.js: Version 18.0.0 or higher
- Claude Desktop: Compatible with MCPB specification
- esbuild: Automatically installed as dev dependency
# Clone or download the extension
cd things-mcpb
# Install dependencies
npm install
# Build JXA scripts
npm run build
# Package the extension
npm run package
# Install in Claude Desktop (follow Claude Desktop docs)things-mcpb/
├── manifest.json # MCPB extension manifest
├── package.json # Dependencies and scripts
├── README.md # Documentation
├── CLAUDE.md # Claude Code instructions
├── server/
│ ├── index.js # Main MCP server
│ ├── tool-definitions.js # MCP tool schemas
│ ├── jxa-executor.js # Secure JXA execution engine
│ ├── server-config.js # Configuration constants
│ ├── utils.js # Validation and utilities
│ └── response-formatter.js # Response formatting
├── jxa/
│ ├── build.js # Build system for JXA scripts
│ ├── src/ # Modular JXA source files
│ │ ├── main.js # Entry point and router
│ │ ├── utils.js # Shared utilities
│ │ ├── todos.js # Todo operations
│ │ ├── projects.js # Project operations
│ │ ├── lists.js # List operations
│ │ ├── search.js # Search operations
│ │ ├── tags.js # Tag operations
│ │ └── areas.js # Area operations
│ └── build/ # Generated bundled scripts
└── test/
├── run-tests.js # Test runner
├── unit/ # Unit tests
├── integration/ # Integration tests
└── regression/ # Regression tests
- Separation of Concerns: Modular architecture with clear responsibilities
- Security First: No shell injection risks with
execFileand JSON parameter passing - User-Friendly: Intuitive parameter names and helpful error messages
- Robust Error Handling: Comprehensive error catching and reporting
- Test-Driven: Comprehensive test coverage for reliability
- Performance Optimized: Pre-built scripts with efficient resource usage
- Extensible: Easy to add new tools and functionality
- Modern JavaScript: ES6 modules compiled for JXA compatibility
- Input Validation: All parameters validated for type, length, and content
- No Shell Injection: Uses
execFileinstead ofexec- parameters never touch shell - JSON Parameter Passing: Parameters passed as JSON arguments, not embedded in scripts
- Pattern Detection: Dangerous patterns blocked before execution
- Error Handling: Structured error responses with detailed logging
- Timeout Management: Prevents hanging JXA operations (30s default)
- Safe Execution: Secure command execution with process isolation
- Comprehensive Testing: Security validation covered by automated test suite
# Run comprehensive test suite
npm test
# Run specific test suites
npm run test:unit # Unit tests
npm run test:integration # Integration tests
npm run test:regression # Regression tests
npm run test:watch # Watch mode for development
# Build JXA scripts
npm run build
npm run build:watch # Watch mode
# Syntax validation
npm run validate
# Debug mode
DEBUG=true npm startThe extension includes a comprehensive test suite covering:
- Input Validation: String, date, array, and number validation with security checks
- Parameter Processing: User-friendly parameter conversion and validation
- JXA Execution: Script loading, execution, and error handling
- Security: Pattern detection and safe parameter passing
- Error Handling: Consistent error message formatting and validation
- Date Handling: Timezone-aware date parsing and formatting
- Tag Management: Format conversion and removal scenarios
- List Operations: Built-in list ID mapping verification
- Regression Tests: Specific issue fixes (#3, #5, etc.)
- Add operation to appropriate module in
jxa/src/(e.g.,todos.js) - Update router in
jxa/src/main.js - Add tool definition to
server/tool-definitions.js - Run
npm run buildto generate bundled script - Add tests and update documentation
- Include comprehensive input validation
- Add structured error handling
- Write unit tests for new functionality
- Update documentation for new features
- Test thoroughly with Things 3 on macOS
- Follow established patterns and conventions
- Maintain backward compatibility when possible
Things 3 Not Running
Solution: Launch Things 3 application and ensure it's running (not just in dock)
Permission Errors
Solution:
1. System Preferences > Security & Privacy > Privacy
2. Select "Automation"
3. Grant permission for your terminal/Claude Desktop to control Things 3
Debug Information
# Enable detailed logging
DEBUG=true npm start- Things 3 Issues: Contact Cultured Code support
- Claude Desktop: Follow Claude Desktop documentation
- Extension Issues: Create issue in project repository
MIT License - See package.json for details
- Cultured Code for Things 3 and its automation support
- Anthropic for the Model Context Protocol (MCP) SDK
- esbuild for fast, reliable JavaScript bundling
Built with ❤️ for the Claude Desktop ecosystem