OmniFocus Enhanced MCP server for AI agents

This enhanced MCP server transforms OmniFocus into an AI-powered productivity tool with native custom perspective access, hierarchical task display, and comprehensive task management capabilities. It integrates seamlessly with Claude AI 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 3+ (must be installed and running)
OmniFocus Pro (required for custom perspectives)
Node.js 18+
Claude Code

Core Capabilities

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
}

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}

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"]
}

Native Custom Perspective Access

Access your OmniFocus custom perspectives with hierarchical task display:

# List all your custom perspectives
list_custom_perspectives {"format": "detailed"}

# Get tasks from custom perspective with tree display
get_custom_perspective_tasks {
  "perspectiveName": "今日工作安排",
  "showHierarchy": true,
  "hideCompleted": true
}

# Examples with different perspectives
get_custom_perspective_tasks {
  "perspectiveName": "Today Review",
  "showHierarchy": true
}

get_custom_perspective_tasks {
  "perspectiveName": "Weekly Planning",
  "showHierarchy": false
}

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

list_custom_perspectives - List all custom perspectives with details
get_custom_perspective_tasks - 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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "omnifocus-enhanced" '{"command":"npx","args":["-y","omnifocus-mcp-enhanced"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "omnifocus-enhanced": {
            "command": "npx",
            "args": [
                "-y",
                "omnifocus-mcp-enhanced"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "omnifocus-enhanced": {
            "command": "npx",
            "args": [
                "-y",
                "omnifocus-mcp-enhanced"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect