🚀 OmniFocus MCP Enhanced
🌟 NEW: Native Custom Perspective Access with Hierarchical Display!
Transform OmniFocus into an AI-powered productivity powerhouse with custom perspective support
Enhanced Model Context Protocol (MCP) server for OmniFocus featuring native custom perspective access, hierarchical task display, AI-optimized tool selection, and comprehensive task management. Perfect integration with Claude AI for intelligent workflows.
✨ Key Features
🌟 NEW: Native Custom Perspective Access
- 🎯 Direct Integration - Native access to your OmniFocus custom perspectives via
Perspective.CustomAPI - 🌳 Hierarchical Display - Tree-style task visualization with parent-child relationships
- 🧠 AI-Optimized - Enhanced tool descriptions prevent AI confusion between perspectives and tags
- ⚡ Zero Setup - Works with your existing custom perspectives instantly
🏗️ Complete Task Management
- 🏗️ Complete Subtask Support - Create hierarchical tasks with parent-child relationships
- 🔍 Built-in Perspectives - Access Inbox, Flagged, Forecast, and Tag-based views
- 🚀 Ultimate Task Filter - Advanced filtering beyond OmniFocus native capabilities
- 🎯 Batch Operations - Add/remove multiple tasks efficiently
- 📊 Smart Querying - Find tasks by ID, name, or complex criteria
- 🔄 Full CRUD Operations - Create, read, update, delete tasks and projects
- 📅 Time Management - Due dates, defer dates, estimates, and scheduling
- 🏷️ Advanced Tagging - Tag-based filtering with exact/partial matching
- 🤖 AI Integration - Seamless Claude AI integration for intelligent workflows
📦 Installation
Quick Install (Recommended)
# One-line installation
claude mcp add omnifocus-enhanced -- npx -y omnifocus-mcp-enhanced
Alternative Installation Methods
# Global installation
npm install -g omnifocus-mcp-enhanced
claude mcp add omnifocus-enhanced -- omnifocus-mcp-enhanced
# Local project installation
git clone https://github.com/jqlts1/omnifocus-mcp-enhanced.git
cd omnifocus-mcp-enhanced
npm install && npm run build
claude mcp add omnifocus-enhanced -- node "/path/to/omnifocus-mcp-enhanced/dist/server.js"
📋 Requirements
- macOS 10.15+ - OmniFocus is macOS-only
- OmniFocus 3+ - The application must be installed and running
- OmniFocus Pro - Required for custom perspectives (new features in v1.6.0)
- Node.js 18+ - For running the MCP server
- Claude Code - For MCP integration
🎯 Core Capabilities
1. 🏗️ Subtask Management
Create complex task hierarchies with ease:
// Create subtask by parent task name
{
"name": "Analyze competitor keywords",
"parentTaskName": "SEO Strategy",
"note": "Focus on top 10 competitors",
"dueDate": "2025-01-15",
"estimatedMinutes": 120,
"tags": ["SEO", "Research"]
}
// Create subtask by parent task ID
{
"name": "Write content outline",
"parentTaskId": "loK2xEAY4H1",
"flagged": true,
"estimatedMinutes": 60
}
2. 🔍 Perspective Views
Access all major OmniFocus perspectives programmatically:
# Inbox perspective
get_inbox_tasks {"hideCompleted": true}
# Flagged tasks
get_flagged_tasks {"projectFilter": "SEO Project"}
# Forecast (next 7 days)
get_forecast_tasks {"days": 7, "hideCompleted": true}
# Tasks by tag
get_tasks_by_tag {"tagName": "AI", "exactMatch": false}
3. 🚀 Ultimate Task Filter
Create any perspective imaginable with advanced filtering:
# Time management view (30min tasks due this week)
filter_tasks {
"taskStatus": ["Available", "Next"],
"estimateMax": 30,
"dueThisWeek": true
}
# Deep work view (60+ minute tasks with notes)
filter_tasks {
"estimateMin": 60,
"hasNote": true,
"taskStatus": ["Available"]
}
# Project overdue tasks
filter_tasks {
"projectFilter": "Website Redesign",
"taskStatus": ["Overdue", "DueSoon"]
}
4. 🌟 NEW: Native Custom Perspective Access
Access your OmniFocus custom perspectives with hierarchical task display:
# 🌟 NEW: List all your custom perspectives
list_custom_perspectives {"format": "detailed"}
# 🌳 NEW: Get tasks from custom perspective with tree display
get_custom_perspective_tasks {
"perspectiveName": "今日工作安排", # Your custom perspective name
"showHierarchy": true, # Enable tree display
"hideCompleted": true
}
# Examples with different perspectives
get_custom_perspective_tasks {
"perspectiveName": "Today Review",
"showHierarchy": true
}
get_custom_perspective_tasks {
"perspectiveName": "Weekly Planning",
"showHierarchy": false # Flat display
}
Why This Is Powerful:
- ✅ Native Integration - Uses OmniFocus
Perspective.CustomAPI directly - ✅ Tree Structure - Visual parent-child task relationships with ├─, └─ symbols
- ✅ AI-Friendly - Enhanced descriptions prevent tool selection confusion
- ✅ Professional Output - Clean, readable task hierarchies
5. 🎯 Batch Operations
Efficiently manage multiple tasks:
{
"items": [
{
"type": "task",
"name": "Website Technical SEO",
"projectName": "SEO Project",
"note": "Optimize technical aspects"
},
{
"type": "task",
"name": "Page Speed Optimization",
"parentTaskName": "Website Technical SEO",
"estimatedMinutes": 180,
"flagged": true
},
{
"type": "task",
"name": "Mobile Responsiveness",
"parentTaskName": "Website Technical SEO",
"estimatedMinutes": 90
}
]
}
🛠️ Complete Tool Reference
📊 Database & Task Management
- dump_database - Get OmniFocus database state
- add_omnifocus_task - Create tasks (enhanced with subtask support)
- add_project - Create projects
- remove_item - Delete tasks or projects
- edit_item - Edit tasks or projects
- batch_add_items - Bulk add (enhanced with subtask support)
- batch_remove_items - Bulk remove
- get_task_by_id - Query task information
🔍 Built-in Perspective Tools
- get_inbox_tasks - Inbox perspective
- get_flagged_tasks - Flagged perspective
- get_forecast_tasks - Forecast perspective (due/deferred tasks)
- get_tasks_by_tag - Tag-based filtering
- filter_tasks - Ultimate filtering with unlimited combinations
🌟 Custom Perspective Tools (NEW)
- list_custom_perspectives - 🌟 NEW: List all custom perspectives with details
- get_custom_perspective_tasks - 🌟 NEW: Access custom perspective with hierarchical display
📊 Analytics & Tracking
- get_today_completed_tasks - View today's completed tasks
🚀 Quick Start Examples
Basic Task Creation
# Simple task
add_omnifocus_task {
"name": "Review quarterly goals",
"projectName": "Planning",
"dueDate": "2025-01-31"
}
Advanced Task Management
# Create parent task
add_omnifocus_task {
"name": "Launch Product Campaign",
"projectName": "Marketing",
"dueDate": "2025-02-15",
"tags": ["Campaign", "Priority"]
}
# Add subtasks
add_omnifocus_task {
"name": "Design landing page",
"parentTaskName": "Launch Product Campaign",
"estimatedMinutes": 240,
"flagged": true
}
Smart Task Discovery
# Find high-priority work
filter_tasks {
"flagged": true,
"taskStatus": ["Available"],
"estimateMax": 120,
"hasEstimate": true
}
# Today's completed work
filter_tasks {
"completedToday": true,
"taskStatus": ["Completed"],
"sortBy": "project"
}
🌟 Custom Perspective Usage
# List your custom perspectives
list_custom_perspectives {"format": "detailed"}
# Access a custom perspective with hierarchy
get_custom_perspective_tasks {
"perspectiveName": "Today Review",
"showHierarchy": true,
"hideCompleted": true
}
# Quick flat view of weekly planning
get_custom_perspective_tasks {
"perspectiveName": "Weekly Planning",
"showHierarchy": false
}
🔧 Configuration
Verify Installation
# Check MCP status
claude mcp list
# Test basic connection
get_inbox_tasks
# Test new custom perspective features
list_custom_perspectives
Troubleshooting
- Ensure OmniFocus 3+ is installed and running
- Verify Node.js 18+ is installed
- Check Claude Code MCP configuration
- Enable accessibility permissions for terminal apps if needed
🎯 Use Cases
- Project Management - Create detailed project hierarchies with subtasks
- GTD Workflow - Leverage perspectives for Getting Things Done methodology
- Time Blocking - Filter by estimated time for schedule planning
- Review Process - Use custom perspectives for weekly/monthly reviews
- Team Coordination - Batch operations for team task assignment
- AI-Powered Planning - Let Claude analyze and organize your tasks
📈 Performance
- Fast Filtering - Native AppleScript performance
- Batch Efficiency - Single operation for multiple tasks
- Memory Optimized - Minimal resource usage
- Scalable - Handles large task databases efficiently
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
📄 License
MIT License - see LICENSE file for details.
🔗 Links
- NPM Package: https://www.npmjs.com/package/omnifocus-mcp-enhanced
- GitHub Repository: https://github.com/jqlts1/omnifocus-mcp-enhanced
- OmniFocus: https://www.omnigroup.com/omnifocus/
- Model Context Protocol: https://modelcontextprotocol.io/
- Claude Code: https://docs.anthropic.com/en/docs/claude-code
🙏 Acknowledgments
Based on the original OmniFocus MCP server by themotionmachine. Enhanced with perspective views, advanced filtering, and complete subtask support.
⭐ Star this repo if it helps boost your productivity!