omnifocus-mcp-enhanced

jqlts1/omnifocus-mcp-enhanced

3.4

If you are the rightful owner of omnifocus-mcp-enhanced and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

OmniFocus MCP Enhanced transforms OmniFocus into an AI-powered productivity tool with advanced task management capabilities.

Tools
4
Resources
0
Prompts
0

๐Ÿš€ OmniFocus MCP Enhanced

npm version License: MIT Node.js CI macOS

๐ŸŒŸ 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.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"

๐Ÿ“‹ 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.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
    }
  ]
}

๐Ÿ› ๏ธ Complete Tool Reference

๐Ÿ“Š 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

  1. get_inbox_tasks - Inbox perspective
  2. get_flagged_tasks - Flagged perspective
  3. get_forecast_tasks - Forecast perspective (due/deferred tasks)
  4. get_tasks_by_tag - Tag-based filtering
  5. filter_tasks - Ultimate filtering with unlimited combinations

๐ŸŒŸ Custom Perspective Tools (NEW)

  1. list_custom_perspectives - ๐ŸŒŸ NEW: List all custom perspectives with details
  2. get_custom_perspective_tasks - ๐ŸŒŸ NEW: Access custom perspective with hierarchical display

๐Ÿ“Š Analytics & Tracking

  1. 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.

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

๐Ÿ“„ License

MIT License - see file for details.

๐Ÿ”— Links

๐Ÿ™ 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!