Provides comprehensive task and project management for OmniFocus on macOS, including creating hierarchical tasks, managing folders and projects, accessing built-in and custom perspectives, handling repeating tasks, setting planned dates, managing project reviews, batch operations, and advanced filtering with tag support.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OmniFocus MCP Servershow me all tasks planned for today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
of-mcp
An MCP server for OmniFocus. Originally forked from jqlts1/omnifocus-mcp-enhanced, now maintained independently with additional features.
Transform OmniFocus into an AI-powered productivity powerhouse
Enhanced Model Context Protocol (MCP) server for OmniFocus featuring project review workflow, planned date support, repeating task support, 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
π Project Review Workflow
π Find Due Reviews - Get projects that need review with
get_projects_for_reviewβ Mark Reviewed - Mark projects as reviewed individually or in batch
β° Set Intervals - Configure review intervals in days
π Track Progress - View next review date, last reviewed, and interval for each project
π Planned Date Support
π Schedule Work - Set when you intend to work on a task (separate from due date)
π Filter by Planned - Find tasks planned for today, this week, or date ranges
π Sort by Planned - Order tasks by their planned date
π Full CRUD - Create, read, update, and clear planned dates
π Repeating Tasks
π Flexible Frequencies - Daily, weekly, monthly, or yearly repetition
π― Custom Intervals - Repeat every N days/weeks/months
π Specific Days - Weekly tasks on specific days (e.g., Mon/Wed/Fri)
π Weekday-of-Month - First Monday, last Friday, third Wednesday patterns
π Repeat From - Choose to repeat from due date or completion date
π 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
ποΈ Subtask Support - Create hierarchical tasks with parent-child relationships
π Folder Management - Create and nest folders for project organization
π Built-in Perspectives - Access Inbox, Flagged, Forecast, and Tag-based views
π Ultimate Task Filter - Advanced filtering beyond OmniFocus native capabilities
π― Batch Operations - Add/edit/remove multiple items with true batching (9-12x faster)
π Smart Querying - Find tasks, projects, or folders by ID or name
π Consistent ID Support - All tools accept both IDs and names (IDs take priority for reliability)
π Full CRUD Operations - Create, read, update, delete tasks, projects, and folders
π Time Management - Due dates, defer dates, planned dates, creation dates (displayed in all task outputs), estimates, and scheduling
π·οΈ Advanced Tagging - Multi-tag filtering with any/all matching, exact/partial search, and auto-creation of missing tags
π€ AI Integration - Seamless Claude AI integration for intelligent workflows
π¦ Installation
Clone the repository:
git clone https://github.com/mojenmojen/of-mcp.git cd of-mcp npm install && npm run buildAlternative build (if
npm run buildhangs or runs out of memory):npm run build:fastThis uses esbuild (~14ms) instead of tsc. See Troubleshooting for details.
Add to Claude Code:
claude mcp add omnifocus -- node "/path/to/of-mcp/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 task in project (by name or ID)
{
"name": "Analyze competitor keywords",
"projectName": "SEO Strategy",
"note": "Focus on top 10 competitors",
"dueDate": "2025-01-15",
"estimatedMinutes": 120,
"tags": ["SEO", "Research"]
}
// Create task by project ID
{
"name": "Write content outline",
"projectId": "projectId123",
"flagged": true,
"estimatedMinutes": 60
}
// Create subtask by parent task ID
{
"name": "Research top competitors",
"parentTaskId": "loK2xEAY4H1",
"estimatedMinutes": 30
}2. π Folder Management
Organize projects with nested folders:
# Create a top-level folder
add_folder {
"name": "Work Projects"
}
# Create a nested folder (by name or ID)
add_folder {
"name": "Q1 2025",
"parentFolderName": "Work Projects"
}
add_folder {
"name": "Marketing",
"parentFolderId": "folderId123"
}
# Create a project in a folder (by name or ID)
add_project {
"name": "New Website",
"folderName": "Work Projects"
}
add_project {
"name": "Mobile App",
"folderId": "folderId123"
}3. π Perspective Views
Access all major OmniFocus perspectives:
# Inbox perspective
get_inbox_tasks {"hideCompleted": true}
# Flagged tasks (filter by project name or ID)
get_flagged_tasks {"projectFilter": "SEO Project"}
get_flagged_tasks {"projectId": "abc123xyz"}
# Forecast (next 7 days)
get_forecast_tasks {"days": 7, "hideCompleted": true}
# Tasks by tag name (single or multiple)
get_tasks_by_tag {"tagName": "AI", "exactMatch": false}
get_tasks_by_tag {"tagName": ["work", "urgent", "focus"]}
# Tasks by tag ID (single or multiple)
get_tasks_by_tag {"tagId": "tagId123"}
get_tasks_by_tag {"tagId": ["tagId1", "tagId2"]}
# Tasks by multiple tags (AND - all of these tags)
get_tasks_by_tag {"tagName": ["home", "errands"], "tagMatchMode": "all"}
# Include dropped/inactive tags in search
get_tasks_by_tag {"tagId": "droppedTagId", "includeDropped": true}
# List all tags (fast - ~400ms)
list_tags {}
# List all tags with task counts (slower - ~15s)
list_tags {"showTaskCounts": true}
# Include dropped/inactive tags
list_tags {"includeDropped": true}4. π 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 by name or ID)
filter_tasks {
"projectFilter": "Website Redesign",
"taskStatus": ["Overdue", "DueSoon"]
}
# Find untagged tasks (useful after bulk tag cleanup)
filter_tasks {
"untagged": true,
"taskStatus": ["Available", "Next"]
}
# Filter by project ID and tag ID (for programmatic use)
filter_tasks {
"projectId": "projectId123",
"tagId": ["tagId1", "tagId2"],
"taskStatus": ["Available"]
}5. π Repeating Tasks
Create and manage recurring tasks with flexible repetition rules:
# Daily repeating task
add_omnifocus_task {
"name": "Daily standup notes",
"projectName": "Work",
"dueDate": "2025-01-15",
"repetitionRule": {
"frequency": "daily"
}
}
# Weekly task on Mon/Wed/Fri
add_omnifocus_task {
"name": "Exercise",
"dueDate": "2025-01-15",
"repetitionRule": {
"frequency": "weekly",
"daysOfWeek": [1, 3, 5]
}
}
# Monthly task on the 15th, repeat from completion
add_omnifocus_task {
"name": "Pay bills",
"dueDate": "2025-01-15",
"repetitionRule": {
"frequency": "monthly",
"dayOfMonth": 15,
"repeatFrom": "completion"
}
}
# First Monday of every month (weekday-of-month pattern)
add_omnifocus_task {
"name": "Prepare for monthly HOA meeting",
"dueDate": "2026-02-02",
"repetitionRule": {
"frequency": "monthly",
"weekdayOfMonth": {
"week": 1,
"day": 1
},
"repeatFrom": "due"
}
}
# Last Friday of every month
add_omnifocus_task {
"name": "Monthly expense report",
"dueDate": "2026-01-31",
"repetitionRule": {
"frequency": "monthly",
"weekdayOfMonth": {
"week": -1,
"day": 5
}
}
}
# Third Wednesday of every 2 months
add_omnifocus_task {
"name": "Quarterly planning prep",
"dueDate": "2026-01-21",
"repetitionRule": {
"frequency": "monthly",
"interval": 2,
"weekdayOfMonth": {
"week": 3,
"day": 3
}
}
}
# Edit task to add/remove repetition
edit_item {
"id": "taskId123",
"itemType": "task",
"newRepetitionRule": {"frequency": "weekly", "interval": 2}
}
# Remove repetition from a task
edit_item {
"id": "taskId123",
"itemType": "task",
"newRepetitionRule": null
}
# Move a task to a different project (by ID)
edit_item {
"id": "taskId123",
"itemType": "task",
"newProjectId": "projectId456"
}
# Move a project to a different folder (by ID)
edit_item {
"id": "projectId123",
"itemType": "project",
"newFolderId": "folderId456"
}6. π 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 by name
get_custom_perspective_tasks {
"perspectiveName": "Today's Work", # Your custom perspective name
"showHierarchy": true, # Enable tree display
"hideCompleted": true,
"ignoreFocus": true # Clear Focus mode to see all tasks (default: true)
}
# Get tasks from custom perspective by ID
get_custom_perspective_tasks {
"perspectiveId": "perspectiveId123",
"showHierarchy": 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
}
# Example output (flat view):
# 1. **Review quarterly goals** [ID: j-Q4cm6ewVF]
# Tags: planning
# Due: 1/31/2025
# Example output (hierarchical view):
# ββ **Launch Product Campaign**
# β ID: abc123xyz
# β Tags: Campaign, Priority
# β Due: 2/15/2025Why This Is Powerful:
β Native Integration - Uses OmniFocus
Perspective.CustomAPI directlyβ Tree Structure - Visual parent-child task relationships with ββ, ββ symbols
β Task IDs Included - Build
omnifocus:///task/{id}deep links directly from outputβ AI-Friendly - Enhanced descriptions prevent tool selection confusion
β Professional Output - Clean, readable task hierarchies
7. π Batch Filter Tasks
Filter tasks across multiple projects in a single call (much faster than multiple filter_tasks calls):
# Get tasks from multiple projects at once
batch_filter_tasks {
"projectNames": ["Website Redesign", "Marketing Campaign", "Q1 Planning"],
"taskStatus": ["Available", "Next", "Blocked"],
"limit": 50
}
# Filter by project IDs for reliability
batch_filter_tasks {
"projectIds": ["projectId1", "projectId2", "projectId3"],
"taskStatus": ["Available", "Overdue"],
"flagged": true
}
# Combine with due date filters
batch_filter_tasks {
"projectNames": ["Daily Tasks", "Weekly Review"],
"dueThisWeek": true,
"sortBy": "dueDate"
}Benefits:
Single API call instead of N calls for N projects
Results grouped by project with task counts
Supports all common filters (status, flagged, due dates)
Returns project IDs for follow-up operations
8. π― Batch Write Operations
Efficiently manage multiple tasks with true batching (9-12x faster than individual calls):
# Batch add multiple tasks/projects (by name or ID)
batch_add_items {
"items": [
{
"type": "task",
"name": "Website Technical SEO",
"projectName": "SEO Project", # or use projectId
"note": "Optimize technical aspects"
},
{
"type": "task",
"name": "Page Speed Optimization",
"parentTaskName": "Website Technical SEO", # or use parentTaskId
"estimatedMinutes": 180,
"flagged": true
},
{
"type": "project",
"name": "New Project",
"folderId": "folderId123" # or use folderName
}
]
}
# Batch edit multiple items
batch_edit_items {
"edits": [
{
"id": "taskId1",
"itemType": "task",
"newStatus": "completed"
},
{
"id": "taskId2",
"itemType": "task",
"newDueDate": "2025-02-01",
"newFlagged": true,
"newProjectId": "projectId123" # Move task to another project by ID
},
{
"id": "projectId1",
"itemType": "project",
"newNote": "Updated via batch edit",
"newFolderName": "Work Projects" # Move project to another folder by name
}
]
}
# Batch update tags (works on both tasks AND projects, auto-creates missing tags)
batch_edit_items {
"edits": [
{
"id": "taskId1",
"itemType": "task",
"addTags": ["urgent", "review"],
"removeTags": ["someday"]
},
{
"id": "projectId1",
"itemType": "project",
"addTags": ["Q1", "active"]
},
{
"id": "taskId2",
"itemType": "task",
"replaceTags": ["priority", "work"]
}
]
}
# Batch remove multiple items
batch_remove_items {
"items": [
{"id": "taskId1", "itemType": "task"},
{"id": "taskId2", "itemType": "task"},
{"name": "Old Project", "itemType": "project"}
]
}9. π Project Review Workflow
Automate your weekly review process:
# Get all projects due for review
get_projects_for_review {
"includeOnHold": false,
"limit": 50
}
# Mark a single project as reviewed
edit_item {
"id": "projectId123",
"itemType": "project",
"markReviewed": true
}
# Set a project's review interval to 14 days
edit_item {
"id": "projectId123",
"itemType": "project",
"newReviewInterval": 14
}
# Batch mark multiple projects as reviewed (by ID)
batch_mark_reviewed {
"projectIds": ["projectId1", "projectId2", "projectId3"]
}
# Batch mark by project names
batch_mark_reviewed {
"projectNames": ["Marketing Campaign", "Website Redesign"]
}
# View project review info
get_project_by_id {
"projectName": "My Project"
}
# Returns: reviewInterval, nextReviewDate, lastReviewDateReview Workflow Benefits:
Automate finding projects that need attention
Mark multiple projects reviewed in one operation
Track when each project was last reviewed
Set custom review intervals per project
π οΈ Complete Tool Reference
π Database & Task Management
add_omnifocus_task - Create tasks (enhanced with subtask support)
add_project - Create projects
add_folder - Create folders (with nesting support)
remove_item - Delete tasks or projects
edit_item - Edit tasks or projects
batch_add_items - Bulk add tasks/projects (true batching - 9x faster)
batch_edit_items - Bulk edit tasks/projects (true batching - 12x faster)
batch_remove_items - Bulk remove (true batching - 9x faster)
get_task_by_id - Query task information
list_projects - List projects with folder/status filtering
π 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 (single or multiple tags with any/all matching)
list_tags - List all tags with task counts and hierarchy
filter_tasks - Ultimate filtering with unlimited combinations
batch_filter_tasks - Filter multiple projects in one call (faster than multiple filter_tasks)
π 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
π Project Review Tools
get_projects_for_review - Get projects due for review
batch_mark_reviewed - Mark multiple projects as reviewed
π§ Utility Tools
get_server_version - Get server version and build information
get_project_by_id - Query project information by ID or name (includes review data)
get_folder_by_id - Query folder information by ID or name
diagnose_connection - Check OmniFocus connectivity and permissions
π New Tools (v1.23.0)
search_tasks - Full-text search across task names and notes (simpler than filter_tasks)
duplicate_project - Create a copy of a project including all tasks (great for templates)
edit_tag - Edit tag properties: rename, change status, move to parent, or set allowsNextAction
π New Tools (v1.27.0) - AI Assistant Optimizations
get_system_health - Get all health metrics in ONE call (inbox, projects, tasks, tags, flagged, untagged)
get_completion_stats - Get completion counts grouped by project/tag/folder for a date range
π 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
}π Search Tasks (New in v1.23.0)
# Simple text search across names and notes
search_tasks {
"query": "budget report"
}
# Search with match modes
search_tasks {
"query": "meeting budget",
"matchMode": "anyWord" # matches either "meeting" or "budget"
}
search_tasks {
"query": "quarterly review",
"matchMode": "allWords", # must contain both words
"includeCompleted": true
}
# Search within a specific project
search_tasks {
"query": "design",
"projectName": "Website Redesign",
"searchIn": "name" # only search task names, not notes
}π Duplicate Project (New in v1.23.0)
# Create a copy of a template project
duplicate_project {
"sourceProjectName": "Sprint Template",
"newName": "Sprint 15"
}
# Duplicate with date shifting (great for recurring workflows)
duplicate_project {
"sourceProjectName": "Weekly Review Checklist",
"newName": "Week 3 Review",
"shiftDates": {
"referenceDate": "2026-01-20",
"basedOn": "defer"
}
}
# Duplicate into a specific folder
duplicate_project {
"sourceProjectId": "templateProjectId123",
"newName": "Q1 Marketing Campaign",
"folderName": "2026 Projects",
"clearCompleted": true,
"copyTags": true
}π·οΈ Edit Tag (New in v1.23.0)
# Reactivate a dropped tag
edit_tag {
"tagName": "prep",
"newStatus": "active"
}
# Put a tag on hold (tasks with this tag become blocked)
edit_tag {
"tagName": "office",
"newStatus": "onHold"
}
# Rename a tag
edit_tag {
"tagId": "tagId123",
"newName": "high-priority"
}
# Move tag to a different parent
edit_tag {
"tagName": "errands",
"newParentTagName": "personal"
}
# Make a tag top-level (remove from parent)
edit_tag {
"tagName": "urgent",
"newParentTagId": ""
}π€ AI Assistant Efficiency Guide
Use batch_filter_tasks for Multi-Project Queries
Instead of making separate filter_tasks calls for each project:
# β Inefficient - 5 API calls
filter_tasks { "projectFilter": "Project A", "taskStatus": [...] }
filter_tasks { "projectFilter": "Project B", "taskStatus": [...] }
filter_tasks { "projectFilter": "Project C", "taskStatus": [...] }
# ... etcUse a single batch call:
# β
Efficient - 1 API call
batch_filter_tasks {
"projectNames": ["Project A", "Project B", "Project C", "Project D", "Project E"],
"taskStatus": ["Available", "Next", "Blocked", "DueSoon", "Overdue"],
"limit": 100
}Use IDs for Reliability
All tools support both name and ID parameters. IDs are more reliable because they don't change when items are renamed.
Tool | ID Parameter | Alternative To |
|
|
|
|
|
|
|
| name equivalents |
|
| name equivalents |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Rule: When both ID and name are provided, ID takes priority.
Batch Operations for Writes
Use batch tools for multiple write operations:
batch_add_items- Add multiple tasks/projects (9x faster)batch_edit_items- Edit multiple items (12x faster)batch_remove_items- Remove multiple items (9x faster)
π§ Configuration
Verify Installation
# Check MCP status
claude mcp list
# Verify server version
get_server_version
# Test basic connection
get_inbox_tasks
# Test custom perspective features
list_custom_perspectivesAnalytics & Health Checks (v1.27.0)
# Get all health metrics in ONE call (replaces 6+ separate calls)
get_system_health
# Get completion stats by project for last month
get_completion_stats {
"completedAfter": "2026-01-01",
"completedBefore": "2026-02-01",
"groupBy": "project"
}
# Get completion stats by tag
get_completion_stats {
"completedAfter": "2026-01-01",
"completedBefore": "2026-02-01",
"groupBy": "tag"
}
# Fast count-only query (no task data returned)
filter_tasks {
"taskStatus": ["Available", "Next"],
"countOnly": true
}Troubleshooting
Build issues:
If
npm run buildhangs or crashes with OOM, usenpm run build:fastinsteadThe
build:fastscript uses esbuild which skips type checking but produces identical outputThis can happen due to complex type inference in the MCP SDK and Zod dependencies
For type checking, run
npx tsc --noEmitseparately or rely on your IDE
Runtime issues:
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
get_server_versionto verify the correct version is loaded after updates
π― 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
Weekly Reviews - Automate project reviews with
get_projects_for_reviewandbatch_mark_reviewedTeam Coordination - Batch operations for team task assignment
AI-Powered Planning - Let Claude analyze and organize your tasks
π Performance
True Batch Operations - All batch tools execute in a single OmniFocus script call
batch_add_items: ~138ms per item (9x faster than individual calls)batch_edit_items: ~76ms per item (12x faster than individual calls)batch_remove_items: ~65ms per item (9x faster than individual calls)
Fast ID Lookups - Direct
Task.byIdentifier()/Project.byIdentifier()API callsLazy Loading - OmniFocus collections only loaded when needed
Fast Filtering - Native AppleScript/OmniJS performance
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
Release Checklist
When releasing a new version:
Bump version in
package.jsonUpdate this README with any new features or tools
Commit and push changes
π License
MIT License - see LICENSE file for details.
π Links
This Fork: https://github.com/mojenmojen/of-mcp
Original Project: 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!