Omnifocus MCP Enhanced

🚀 OmniFocus MCP Enhanced

🌟 NEW: Native Custom Perspective Access with Hierarchical Display!

Transform OmniFocus into an AI-powered productivity powerhouse with custom perspective support

This is an Enhanced Model Context Protocol (MCP) server for OmniFocus, featuring native custom perspective access, hierarchical task display, AI-optimized tool selection, and comprehensive task management. It integrates perfectly with Claude AI for intelligent workflows.

🚀 Quick Start

Transform OmniFocus into an AI - powered productivity tool with custom perspective support. Start using it by following the installation steps below and explore its various features through the provided examples.

✨ Features

🌟 NEW: Native Custom Perspective Access

• 🎯 Direct Integration: Native access to your OmniFocus custom perspectives via the Perspective.Custom API.
• 🌳 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"

💻 Usage Examples

Basic Usage

# Simple task
add_omnifocus_task {
  "name": "Review quarterly goals",
  "projectName": "Planning",
  "dueDate": "2025-01-31"
}

Advanced Usage

# 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
}

📚 Documentation

📊 Database & Task Management

1. dump_database: Get OmniFocus database state.
2. add_omnifocus_task: Create tasks (enhanced with subtask support).
3. add_project: Create projects.
4. remove_item: Delete tasks or projects.
5. edit_item: Edit tasks or projects.
6. batch_add_items: Bulk add (enhanced with subtask support).
7. batch_remove_items: Bulk remove.
8. get_task_by_id: Query task information.

🔍 Built - in Perspective Tools

9. get_inbox_tasks: Inbox perspective.
10. get_flagged_tasks: Flagged perspective.
11. get_forecast_tasks: Forecast perspective (due/deferred tasks).
12. get_tasks_by_tag: Tag - based filtering.
13. filter_tasks: Ultimate filtering with unlimited combinations.

🌟 Custom Perspective Tools (NEW)

14. list_custom_perspectives: 🌟 NEW: List all custom perspectives with details.
15. get_custom_perspective_tasks: 🌟 NEW: Access custom perspective with hierarchical display.

📊 Analytics & Tracking

16. get_today_completed_tasks: View today's completed tasks.

🔧 Technical Details

Core Capabilities

1. 🏗️ Subtask Management

Create complex task hierarchies easily:

// 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.Custom API 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
    }
  ]
}

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.

📄 License

This project is under the MIT License. See the 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

This project is based on the original OmniFocus MCP server by [themotionmachine](https://github.com/themotionmachine/OmniFocus - MCP). It has been enhanced with perspective views, advanced filtering, and complete subtask support.

⭐ Star this repo if it helps boost your productivity!