{"id":30940765,"url":"https://github.com/ebowman/mcp-server-things","last_synced_at":"2025-09-13T05:16:35.716Z","repository":{"id":313609701,"uuid":"1044738937","full_name":"ebowman/mcp-server-things","owner":"ebowman","description":"A rich MCP server for Things","archived":false,"fork":false,"pushed_at":"2025-09-07T09:55:18.000Z","size":1473,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-07T10:11:52.979Z","etag":null,"topics":["mcp","mcp-server","things3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ebowman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-26T06:21:06.000Z","updated_at":"2025-09-07T09:04:37.000Z","dependencies_parsed_at":"2025-09-07T10:11:58.770Z","dependency_job_id":"abd36034-e3d0-4095-9c5e-eb3c8721ee59","html_url":"https://github.com/ebowman/mcp-server-things","commit_stats":null,"previous_names":["ebowman/mcp-server-things"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ebowman/mcp-server-things","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebowman%2Fmcp-server-things","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebowman%2Fmcp-server-things/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebowman%2Fmcp-server-things/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebowman%2Fmcp-server-things/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ebowman","download_url":"https://codeload.github.com/ebowman/mcp-server-things/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ebowman%2Fmcp-server-things/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274527936,"owners_count":25302320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","things3"],"created_at":"2025-09-10T21:01:33.499Z","updated_at":"2025-09-13T05:16:35.706Z","avatar_url":"https://github.com/ebowman.png","language":"Python","funding_links":[],"categories":["MCP Servers \u0026 Integrations"],"sub_categories":["Other IDEs"],"readme":"# Things 3 MCP Server\n\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![macOS](https://img.shields.io/badge/macOS-12+-green.svg)](https://www.apple.com/macos/)\n\nA Model Context Protocol (MCP) server that connects Claude and other AI assistants to Things 3 for natural language task management.\n\n## Installation\n\n### Option 1: From PyPI (Recommended)\n\n1. Create and activate a virtual environment:\n```bash\npython3 -m venv venv\nsource venv/bin/activate  # On macOS/Linux\n```\n\n2. Install the package:\n```bash\npip install mcp-server-things\n```\n\n### Option 2: From Source (Development)\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/ebowman/mcp-server-things.git\ncd mcp-server-things\n```\n\n2. Create and activate a virtual environment:\n```bash\npython3 -m venv venv\nsource venv/bin/activate  # On macOS/Linux\n```\n\n3. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n4. Install in development mode:\n```bash\npip install -e .\n```\n\n## Claude Desktop Configuration\n\n### For PyPI Installation\n\nAdd to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"things\": {\n      \"command\": \"/path/to/your/venv/bin/python\",\n      \"args\": [\"-m\", \"things_mcp\"],\n      \"env\": {\n        \"THINGS_MCP_LOG_LEVEL\": \"INFO\",\n        \"THINGS_MCP_APPLESCRIPT_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\n### For Source Installation\n\nAdd to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"things\": {\n      \"command\": \"/path/to/mcp-server-things/venv/bin/python\",\n      \"args\": [\"-m\", \"things_mcp\"],\n      \"env\": {\n        \"PYTHONPATH\": \"/path/to/mcp-server-things/src\",\n        \"THINGS_MCP_LOG_LEVEL\": \"INFO\",\n        \"THINGS_MCP_APPLESCRIPT_TIMEOUT\": \"30\"\n      }\n    }\n  }\n}\n```\n\n**Notes:** \n- **PyPI**: Replace `/path/to/your/venv/bin/python` with your virtual environment's Python path\n- **Source**: Replace `/path/to/mcp-server-things` with your actual installation path and include the `PYTHONPATH`\n- Use the full path to the Python executable in your virtual environment\n- See Configuration section below for environment variable options\n\n![Demo showing Claude creating tasks in Things 3](demo.gif)\n*Creating tasks with natural language through Claude*\n\n## 📚 Documentation\n\n- **[User Examples](docs/USER_EXAMPLES.md)** - Rich examples of how to use Things 3 with AI assistants\n- **[Architecture Overview](docs/ARCHITECTURE.md)** - Technical design and implementation details\n- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions\n\n## Features\n\n### Core Todo Operations\n- **Create**: Add todos with full metadata (tags, deadlines, projects, notes, reminders)\n- **Read**: Get todos by ID, project, or built-in lists (Today, Inbox, Upcoming, etc.)\n- **Update**: Modify existing todos with partial updates\n- **Delete**: Remove todos safely\n- **Search**: Find todos by title, notes, or advanced filters\n\n### Project \u0026 Area Management\n- Get all projects and areas with optional task inclusion\n- Create new projects with initial todos\n- Update project metadata and status\n- Organize todos within project hierarchies\n\n### Built-in List Access\n- **Inbox**: Capture new items\n- **Today**: Items scheduled for today\n- **Upcoming**: Future scheduled items\n- **Anytime**: Items without specific dates\n- **Someday**: Items for future consideration\n- **Logbook**: Completed items history\n- **Trash**: Deleted items\n\n### Advanced Features\n- **Reminder Support**: Create todos with specific reminder times (e.g., \"today@14:30\")\n  - Uses hybrid approach: AppleScript for regular todos, URL scheme for reminders\n  - This works around AppleScript API limitation (cannot set reminder times)\n- **Tag Management**: Full tag support with AI creation control\n- **Date-Range Queries**: Get todos due/activating within specific timeframes\n- **URL Schemes**: Native Things 3 URL scheme integration\n- **Health Monitoring**: System health checks and queue status monitoring\n- **Error Handling**: Robust error handling with configurable retries\n- **Logging**: Structured logging with configurable levels\n- **Concurrency Support**: Multi-client safe operation with operation queuing\n- **Input Validation**: Configurable limits for titles, notes, and tags\n\n## Requirements\n\n- **macOS**: This server requires macOS (tested on macOS 12+)\n- **Things 3**: Things 3 must be installed and accessible\n- **Python**: Python 3.8 or higher\n- **Permissions**: AppleScript permissions for Things 3 access\n\n## Quick Start\n\nOnce installed, Claude (or other MCP clients) can automatically discover and use all available tools. No additional setup required.\n\n## Configuration\n\nThe server uses environment variables for configuration. You can set these variables in three ways:\n1. System environment variables\n2. A `.env` file (automatically loaded from the current directory)\n3. A custom `.env` file specified with `--env-file`\n\n### Using the .env File\n\n1. **Review the example configuration:**\n   ```bash\n   cat .env.example\n   ```\n\n2. **Create your own .env file:**\n   ```bash\n   cp .env.example .env\n   # Edit .env to customize settings\n   ```\n\n3. **Or use a custom location:**\n   ```bash\n   cp .env.example ~/my-things-config.env\n   python -m things_mcp --env-file ~/my-things-config.env\n   ```\n\n### Key Configuration Options\n\n```bash\n# Server identification\nTHINGS_MCP_SERVER_NAME=things3-mcp-server\nTHINGS_MCP_SERVER_VERSION=1.0.0\n\n# AppleScript execution\nTHINGS_MCP_APPLESCRIPT_TIMEOUT=30.0       # Timeout in seconds (1-300)\nTHINGS_MCP_APPLESCRIPT_RETRY_COUNT=3      # Retry attempts (0-10)\n\n# Tag management - Control AI tag creation\nTHINGS_MCP_AI_CAN_CREATE_TAGS=false       # false = AI can only use existing tags\nTHINGS_MCP_TAG_VALIDATION_CASE_SENSITIVE=false\n\n# Logging\nTHINGS_MCP_LOG_LEVEL=INFO                 # DEBUG, INFO, WARNING, ERROR, CRITICAL\nTHINGS_MCP_LOG_FILE_PATH=/path/to/file.log # Optional: log to file instead of console\n\n# Validation limits\nTHINGS_MCP_MAX_TITLE_LENGTH=500\nTHINGS_MCP_MAX_NOTES_LENGTH=10000\nTHINGS_MCP_MAX_TAGS_PER_ITEM=20\nTHINGS_MCP_SEARCH_RESULTS_LIMIT=100\n```\n\n### Command Line Options\n\nThe server supports several command-line options:\n\n```bash\n# Start with debug logging\npython -m things_mcp --debug\n\n# Use a custom .env file\npython -m things_mcp --env-file ~/my-config.env\n\n# Check system health\npython -m things_mcp --health-check\n\n# Test AppleScript connectivity\npython -m things_mcp --test-applescript\n\n# Show version\npython -m things_mcp --version\n\n# Customize timeout and retry settings\npython -m things_mcp --timeout 60 --retry-count 5\n```\n\n### Claude Desktop Environment Variables\n\nYou can set environment variables directly in your Claude Desktop configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"things\": {\n      \"env\": {\n        \"THINGS_MCP_LOG_LEVEL\": \"DEBUG\",\n        \"THINGS_MCP_AI_CAN_CREATE_TAGS\": \"true\",\n        \"THINGS_MCP_APPLESCRIPT_TIMEOUT\": \"60\"\n      }\n    }\n  }\n}\n```\n\n## Available MCP Tools\n\n### Todo Management\n- `get_todos(project_uuid?, include_items?)` - List todos\n- `add_todo(title, ...)` - Create new todo with optional reminder time\n- `update_todo(id, ...)` - Update existing todo\n- `get_todo_by_id(todo_id)` - Get specific todo\n- `delete_todo(todo_id)` - Delete todo\n\n### Project Management\n- `get_projects(include_items?)` - List projects\n- `add_project(title, ...)` - Create new project\n- `update_project(id, ...)` - Update existing project\n\n### Area Management\n- `get_areas(include_items?)` - List areas\n\n### List Access\n- `get_inbox()` - Get Inbox todos\n- `get_today()` - Get Today's todos\n- `get_upcoming()` - Get upcoming todos\n- `get_anytime()` - Get Anytime todos\n- `get_someday()` - Get Someday todos\n- `get_logbook(limit?, period?)` - Get completed todos\n- `get_trash()` - Get trashed todos\n\n### Date-Range Queries\n- `get_due_in_days(days)` - Get todos due within specified days\n- `get_activating_in_days(days)` - Get todos activating within days\n- `get_upcoming_in_days(days)` - Get todos due or activating within days\n\n### Search \u0026 Tags\n- `search_todos(query)` - Basic search\n- `search_advanced(...)` - Advanced search with filters\n- `get_tags(include_items?)` - List tags\n- `create_tag(name)` - Create a new tag\n- `get_tagged_items(tag)` - Get items with specific tag\n- `add_tags(todo_id, tags)` - Add tags to a todo\n- `remove_tags(todo_id, tags)` - Remove tags from a todo\n- `get_recent(period)` - Get recently created items\n\n### Bulk Operations\n- `move_record(record_id, to_parent_uuid)` - Move single record\n- `bulk_move_records(record_ids, to_parent_uuid)` - Move multiple records\n\n### System \u0026 Utilities\n- `health_check()` - Check server and Things 3 status\n- `queue_status()` - Check operation queue status and statistics\n- `get_server_capabilities()` - Get server features and configuration\n- `get_usage_recommendations()` - Get usage tips and best practices\n- `context_stats()` - Get context-aware response statistics\n\n\n## Troubleshooting\n\n### Common Issues\n\n#### Permission Denied Errors\n```bash\n# Grant AppleScript permissions to your terminal/IDE\n# System Preferences \u003e Security \u0026 Privacy \u003e Privacy \u003e Automation\n# Enable access for your terminal application to control Things 3\n```\n\n#### Things 3 Not Found\n```bash\n# Verify Things 3 is installed and running\npython -m things_mcp.main --health-check\n\n# Check if Things 3 is in Applications folder\nls /Applications/ | grep -i things\n```\n\n#### Connection Timeouts\n```bash\n# Increase timeout value via environment variable\nexport THINGS_MCP_APPLESCRIPT_TIMEOUT=60\n\n# Or in your .env file\nTHINGS_MCP_APPLESCRIPT_TIMEOUT=60\n```\n\n### Debug Mode\n\n```bash\n# Enable debug logging\npython -m things_mcp.main --debug\n\n# Check logs\ntail -f things_mcp.log\n```\n\n### Health Diagnostics\n\n```bash\n# Comprehensive health check\npython -m things_mcp.main --health-check\n\n# Test specific components\npython -m things_mcp.main --test-applescript\n```\n\n## Performance\n\n- **Startup Time**: Less than 2 seconds\n- **Response Time**: Less than 500ms for most operations\n- **Memory Usage**: 15MB baseline, 50MB under concurrent load\n- **Concurrent Requests**: Serialized write operations to prevent conflicts\n- **Throughput**: Multiple operations per second depending on complexity\n- **Queue Processing**: Less than 50ms latency for operation enqueuing\n\n## Security\n\n- No network access required (local AppleScript only)\n- No data stored outside of Things 3\n- Minimal system permissions needed\n- Secure AppleScript execution with timeouts\n- Input validation on all parameters\n\n## Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n- Set up a virtual environment and install dependencies\n- Follow existing code style and patterns\n- Add tests for new features\n- Submit pull requests with clear descriptions\n\n## Documentation\n\n- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions\n- [Development Roadmap](docs/ROADMAP.md) - Implementation status and missing features\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/ebowman/mcp-server-things/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/ebowman/mcp-server-things/discussions)\n- **Email**: ebowman@boboco.ie\n\n## Roadmap\n\n### Phase 1: Core Stability (Current)\n- Complete MCP tool implementation (Completed)\n- Robust error handling and logging (Completed)\n- Comprehensive testing suite (Completed)\n- Documentation and examples (Completed)\n\n### Phase 2: Enhanced Features\n- Multi-client concurrency support with operation queuing (Completed)\n- Configurable tag creation policies (Completed)\n- Reminder support with datetime scheduling (Completed)\n- Date-range query tools (Completed)\n- Bulk move operations (Completed)\n- Real-time sync with Things 3 changes (Planned)\n- Advanced natural language processing (Planned)\n- Integration with calendar and email (Planned)\n\n### Phase 3: Advanced Integration\n- Multi-user support (Planned)\n- API rate limiting (Planned)\n- Webhook support (Planned)\n- Analytics and reporting (Planned)\n\n---\n\nBuilt for the Things 3 and MCP community.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febowman%2Fmcp-server-things","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Febowman%2Fmcp-server-things","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febowman%2Fmcp-server-things/lists"}