Used for managing environment variables, particularly for storing the Things authentication token.
Required for the MCP server as Things is a Mac-only application that depends on macOS for its URL scheme functionality.
Provides the runtime environment for the MCP server, with version 18.0.0 or higher required.
Referenced as a testing environment for Things URL schemes, which may need permissions to be granted when opening Things URLs.
Things MCP Server
A Model Context Protocol (MCP) server that interfaces with the Mac application "Things" (by Cultured Code) through its URL scheme. This enables AI assistants and other applications to interact with Things for task management operations.
Overview
This MCP server allows you to control the Things app on macOS through standardized MCP protocol commands. The first iteration implements basic navigation functionality, with plans to expand to full task management capabilities.
Requirements
macOS: Things is a Mac-only application
Node.js: Version 18.0.0 or higher (LTS recommended)
Things App: Must be installed and accessible via URL scheme
Authentication Token: Required for some operations (stored in environment variables)
Installation
Clone or download this repository
git clone <repository-url> cd things-mcp-serverInstall dependencies
npm installSet up environment variables (optional for basic show commands) Create a
.env
file in the root directory:THINGS_AUTHENTICATION_TOKEN=your_auth_token_hereVerify Things app is installed Make sure the Things app is installed on your Mac and can be opened normally.
Usage
As an MCP Server
Start the MCP server:
The server will start and listen for MCP protocol messages via stdin/stdout. You can then connect any MCP-compatible client to use the available tools.
Manual Testing
Test the functionality directly:
These run manual test scripts that verify the Things integration is working correctly.
Available Tools
Currently implemented tools:
Navigation Tools:
show_today_list: Navigate to the Things "Today" list view
No parameters required
Opens Things app and displays today's tasks
show_inbox: Navigate to the Things "Inbox" list view
No parameters required
Opens Things app and displays unorganized tasks
show_upcoming: Navigate to the Things "Upcoming" list view
No parameters required
Opens Things app and displays future scheduled tasks
show_anytime: Navigate to the Things "Anytime" list view
No parameters required
Opens Things app and displays tasks scheduled for anytime
show_someday: Navigate to the Things "Someday" list view
No parameters required
Opens Things app and displays someday/maybe tasks
show_projects: Navigate to the Things "Projects" list view
No parameters required
Opens Things app and displays all active projects
show_areas: Navigate to the Things "Areas" list view
No parameters required
Opens Things app and displays all areas of responsibility
show_logbook: Navigate to the Things "Logbook" view
No parameters required
Opens Things app and displays completed tasks and projects
Content Creation Tools:
add_todo: Create new to-do items
Required: title
Optional: notes, when, deadline, tags, checklist, list
Creates a new task in Things with specified details
add_project: Create new projects
Required: title
Optional: notes, when, deadline, tags, area, todos
Creates a new project with optional initial to-dos
Search Tools:
search: Search Things content
Required: query
Opens Things and displays search results for the query
Update Tools:
update_todo: Update existing to-do items
Required: id (Things ID or title)
Optional: title, notes, when, deadline, tags, checklist, list
Modifies properties of an existing to-do
update_project: Update existing projects
Required: id (Things ID or title)
Optional: title, notes, when, deadline, tags, area
Modifies properties of an existing project
complete_todo: Mark to-do items as completed
Required: id (Things ID or title)
Marks the specified to-do as completed
Batch Tools:
batch_add_todos: Create multiple to-do items at once
Required: todos (array of todo objects)
Optional: Each todo can have title, notes, when, deadline, tags, list
Creates multiple tasks efficiently in a single operation
batch_complete_todos: Mark multiple to-do items as completed
Required: ids (array of todo IDs or titles)
Marks multiple tasks as completed in a single operation
batch_update_todos: Update multiple to-do items with the same changes
Required: ids (array of todo IDs), updates (object with changes)
Optional updates: title, notes, when, deadline, tags, list
Applies the same changes to multiple tasks efficiently
Advanced Tools (v1.4):
search_advanced: Enhanced search with filters and parameters
Required: query (search string)
Optional filters: status, type, area, project, tag, list, date_range, limit
Provides sophisticated search capabilities with multiple filter options
create_project_template: Create projects from predefined templates
Required: template_name, project_title
Templates: software_project, marketing_campaign, event_planning, research_project, custom
Optional: project_notes, area, tags, when, deadline, custom_todos
Creates structured projects with template-based to-dos
json_command: Execute complex operations using JSON commands
Required: command_type, payload
Supports: create_workspace, bulk_import, project_hierarchy, advanced_update
Enables sophisticated operations beyond simple URL parameters
show_filtered_view: Navigate to specific Things views and items
Required: view_type (today, inbox, upcoming, anytime, someday, projects, areas, logbook)
Optional: item_id (for specific items), search_query (for search-based navigation)
Opens filtered views in Things app since URL scheme doesn't support data retrieval
Project Structure
Configuration
Environment Variables
THINGS_AUTHENTICATION_TOKEN
: Required for write operations (optional for show commands)
MCP Client Configuration
When connecting with an MCP client, use:
Server command:
node src/index.js
Working directory: Path to this project
Transport: stdio
Troubleshooting
Common Issues
"Things app is not available"
Ensure you're running on macOS
Verify Things app is installed
Check that Things can be opened manually
"Permission denied" or URL scheme errors
macOS may prompt for permission to open Things
Grant permission when prompted
Try opening a Things URL manually in Safari to test
Module import errors
Ensure Node.js version is 18.0.0 or higher
Run
npm install
to install dependenciesCheck that
"type": "module"
is in package.json
MCP connection issues
Verify your MCP client supports the stdio transport
Check that the server starts without errors
Ensure proper working directory is set
Testing
Run the manual test to verify everything works:
This will attempt to open the Things Today list and report success or failure.
Development
Adding New Tools
Create tool definitions in the appropriate module (e.g.,
src/tools/
)Register tools in
src/index.js
Add tests in
examples/
Update documentation
Code Style
Use ES6+ features with comprehensive comments
Follow async/await pattern for asynchronous operations
Include JSDoc comments for all public functions
Explain Node.js concepts for developers new to the ecosystem
Roadmap
Current: Core Commands (v1.1) ✅
✅ MCP server infrastructure
✅ Things URL scheme integration
✅ show_today_list tool
✅ add_todo: Create new to-dos
✅ add_project: Create new projects
✅ search: Search Things content
Current: Advanced Features (v1.3) ✅
✅ Additional navigation tools (show_inbox, show_upcoming, show_anytime, show_someday, show_projects, show_areas, show_logbook)
✅ Batch operations (batch_add_todos, batch_complete_todos, batch_update_todos)
✅ Enhanced error handling and comprehensive validation utilities
Current: Future Enhancements (v1.4) ✅
✅ x-callback-url support for getting return values from Things
✅ JSON command support for complex operations
✅ Enhanced search with filters and parameters
✅ Project templates and advanced project management
Next: Enterprise Features (v1.5)
Webhook integration for real-time updates
Advanced reporting and analytics
Multi-user workspace management
API rate limiting and optimization
Contributing
Follow the existing code style and comment patterns
Add comprehensive tests for new functionality
Update documentation for any new features
Ensure compatibility with macOS and Things app requirements
License
MIT License - see LICENSE file for details
Support
For issues related to:
This MCP server: Create an issue in this repository
Things app: Contact Cultured Code support
MCP protocol: Refer to the official MCP documentation
This server cannot be installed
A Model Context Protocol server that enables AI assistants to interact with the Mac application 'Things' for task management operations through its URL scheme.
Related MCP Servers
- -securityFlicense-qualityA versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.Last updated -18
- -securityFlicense-qualityA Model Context Protocol server that provides persistent task management capabilities for AI assistants, allowing them to create, update, and track tasks beyond their usual context limitations.Last updated -4
- -securityFlicense-qualityA comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.Last updated -331
- AsecurityFlicenseAqualityA Model Context Protocol server that enables AI assistants to interact with Apple Reminders on macOS, allowing users to view lists, retrieve, create, complete, and delete reminders through natural language.Last updated -56