Skip to main content
Glama

OmniFocus MCP Server

CI Coverage Python License: MIT

A comprehensive, fast, reliable, and agent-friendly MCP server for OmniFocus on macOS.

Why This Server

Comprehensive

21 tools covering projects, tasks, folders, tags, perspectives, and focus. Full CRUD with unified batch operations (Pydantic model inputs), 20+ filter types on task and project queries, and date management including recurrence (RRULE read/write).

Fast

Sub-second reads on filtered queries, even with hundreds of tasks in the database.

Operation

Time

Items

Database

Get flagged tasks

0.66s

14

202 tasks

Get overdue tasks

0.69s

8

202 tasks

Get next tasks

0.66s

27

202 tasks

Get inbox tasks

0.64s

10

202 tasks

Search tasks by keyword

1.07s

37

202 tasks

Get all tasks (unfiltered)

2.20s

202

202 tasks

Get all projects

0.57s

35

35 projects

Create or update a task

0.9s

—

—

Full profiling data: PERFORMANCE_PROFILING.md

Reliable

93% code coverage from 1027 unit tests. 192 integration and E2E tests run against real OmniFocus, plus 5 protocol-level smoke tests verifying the full MCP JSON-RPC transport. Tests cover task, project, and tag lifecycles, filtering, hierarchy, dates, recurrence, and review workflows.

Agent-Friendly

73-scenario blind eval suite with frontier models scoring 100% and popular open-weight models scoring 90-94% (full results). Agents that have never seen OmniFocus can correctly use every tool from descriptions alone. Scenarios cover tool selection, parameter usage, multi-step workflows, date semantics, recurrence, tag behavior, task movement, text search, and safety-critical operations (drop vs delete, destructive action guardrails). Server instructions teach GTD concepts (task states, project types, sequential dependencies, review cycles) so agents make informed decisions, not just API calls.

Related MCP server: OmniFocus MCP Server

Tools (21)

Projects (6)

  • get_projects — filter by ID, query, status; includes dates, review info, task health, stalled detection

  • create_project — with folder placement, dates, review interval, project type

  • update_project — all properties: name, note, status, dates, folder, review settings

  • update_projects — batch update (status, dates, folder, review settings)

  • delete_projects — single or batch

  • reorder_project — position relative to siblings within a folder (before/after)

Tasks (6)

  • get_tasks — 14 filter types: by ID, project, parent, tags, status, dates, flags, text search, inbox

  • create_task — with dates, tags, flags, estimated time, parent task, sequential

  • update_task — all properties including recurrence (RRULE), tags (replace/add/remove), hierarchy

  • update_tasks — batch update (dates, flags, tags, status, project)

  • delete_tasks — single or batch

  • reorder_task — position relative to siblings (before/after)

Folders (3)

  • get_folders — hierarchy with paths

  • create_folder — with optional parent

  • update_folder — rename or move to different parent

Tags (4)

  • get_tags — with status and mutual exclusivity info

  • create_tag — with parent nesting and exclusivity

  • update_tag — name, status, exclusivity

  • delete_tags — single or batch

Perspectives (2)

  • get_perspectives — list with type info

  • switch_perspective — navigate to perspective

Navigation (2)

  • set_focus — focus on projects/folders or clear

  • get_focus — current focus state

Prerequisites

  • macOS with OmniFocus installed

  • Python 3.10+

  • uv package manager

Installation

git clone https://github.com/s-morgan-jeffries/omnifocus-mcp.git
cd omnifocus-mcp
git checkout v0.13.2  # Latest stable release

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync --dev

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "omnifocus": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/omnifocus-mcp",
        "run",
        "omnifocus-mcp"
      ]
    }
  }
}

Other MCP Clients

python -m omnifocus_mcp.server_fastmcp

Communicates via stdin/stdout using the MCP protocol.

Permissions

macOS will prompt for:

  • Accessibility access (to control OmniFocus via AppleScript)

  • Automation permissions for OmniFocus

Contributing

Bug reports and feature requests are welcome via GitHub Issues.

License

MIT

Available Tools

21 tools
create_foldersB

Create one or more folders.

Parameters (per item):

  • name: str (required)

  • parent_path: str -- e.g. "Work > Clients"

Inputs: folders (required). Returns: result

create_projectsA

Create one or more projects.

Parameters (per item):

  • name: str (required)

  • note, folder_path: str

  • project_type: str -- "parallel" (default), "sequential", "single_actions"

  • sequential: bool (deprecated, use project_type)

  • review_interval_value: int + review_interval_unit: str ("day"/"week"/"month"/"year"); review_interval_weeks: int (deprecated)

  • completed_by_children: bool

  • due_date, defer_date, planned_date: str -- ISO 8601

Inputs: projects (required). Returns: result

create_tagsB

Create one or more tags.

Parameters (per item):

  • name: str (required)

  • parent_tag: str -- parent by name

  • children_are_mutually_exclusive: bool

Inputs: tags (required). Returns: result

create_tasksA

Create one or more tasks.

Parameters (per item):

  • task_name: str (required)

  • project_id: str -- mutually exclusive with parent_task_id

  • parent_task_id: str -- creates subtask

  • note: str (plain text only)

  • due_date, defer_date, planned_date: str -- ISO 8601

  • flagged: bool

  • tags: list[str] -- must already exist

  • estimated_minutes: int

  • sequential: bool -- subtasks completed in order

  • completed_by_children: bool

Inputs: tasks (required). Returns: result

delete_projectsA

Permanently delete projects and all their tasks. Cannot be undone.

  • project_ids: str | list[str] (required)

Inputs: project_ids (required). Returns: result

delete_tagsB

Delete tags. Tasks lose tag association but are not deleted.

  • tag_ids: str | list[str] (required)

Inputs: tag_ids (required). Returns: result

delete_tasksC

Permanently delete tasks. Cannot be undone.

  • task_ids: str | list[str] (required)

Inputs: task_ids (required). Returns: result

get_focusB

Get currently focused items.

Inputs: no named parameters. Returns: result

get_foldersB

Get all folders with hierarchy.

Returns: id, name, path (e.g. "Work > Clients"), status ("active"/"dropped").

Inputs: no named parameters. Returns: result

get_perspectivesA

Get all perspectives.

Returns: name, type (built-in/custom), id

Inputs: no named parameters. Returns: result

get_projectsA

Retrieve projects with optional filtering.

Parameters:

  • project_id: str -- filter to specific project

  • query: str -- search name/note/folder (case-insensitive)

  • flagged_only, on_hold_only, completed_only: bool

  • stalled_only: bool -- active projects with no available next actions

  • include_dropped, include_completed: bool -- include hidden states

  • include_full_notes: bool

  • include_task_health: bool -- adds remainingCount, availableCount, overdueCount, deferredCount, stalled, health

  • include_last_activity: bool -- adds lastActivityDate

  • has_overdue_tasks: bool -- implies include_task_health

  • tag_filter: list[str] -- projects with ALL specified tags

  • due_after, due_before, due_on: str -- ISO date filters for due date

  • defer_after, defer_before, defer_on: str -- ISO date filters for defer date

  • planned_after, planned_before, planned_on: str

  • completion_after, completion_before, completion_on: str

  • dropped_after, dropped_before, dropped_on: str

  • created_after, created_before, created_on: str

  • modified_after, modified_before, modified_on: str

  • min_task_count: int

  • has_no_due_dates: bool

  • sort_by: str -- "name", "due_date", "defer_date", "planned_date", "creation_date", "modification_date", "completion_date", "dropped_date"; sort_order: str -- "asc"/"desc"

Returns: id, name, folderPath, status, projectType, sequential (deprecated), completedByChildren, flagged, creationDate, modificationDate, completionDate, droppedDate, dueDate, deferDate, plannedDate, tags, note, lastReviewDate, nextReviewDate, reviewIntervalValue, reviewIntervalUnit. Optional health/activity fields when requested.

Inputs: project_id, include_full_notes, on_hold_only, query, +34 more. Returns: result

get_tagsA

Retrieve all tags.

Returns: id, name, status ("active"/"on hold"/"dropped"), parentTagId (empty if top-level; create/update accept parent by NAME not ID), childrenAreMutuallyExclusive (assigning one child silently removes siblings).

Inputs: no named parameters. Returns: result

get_tasksA

Get tasks with optional filtering.

Parameters:

  • task_id, parent_task_id, project_id: str

  • query: str -- search name/note

  • flagged_only, available_only, overdue, dropped_only, blocked_only, next_only, inbox_only: bool

  • include_completed: bool

  • include_full_notes: bool

  • tag_filter: list[str]; tag_filter_mode: str -- "and" (default), "or", "not"

  • due_after, due_before, due_on: str -- ISO date filters for due date

  • defer_after, defer_before, defer_on: str -- ISO date filters for defer date

  • planned_after, planned_before, planned_on: str

  • completion_after, completion_before, completion_on: str -- requires include_completed

  • dropped_after, dropped_before, dropped_on: str -- requires dropped_only or include_completed

  • modified_after, modified_before, modified_on, created_after, created_before, created_on: str

  • max_estimated_minutes: int -- quick wins filter

  • has_estimate: bool

  • recurring_only: bool

  • sort_by: str -- "name", "due_date", "defer_date", "planned_date", "creation_date", "modification_date", "completion_date", "dropped_date"; sort_order: str

Returns: id, name, projectName, completed, dropped, blocked, available, next, flagged, dueDate, deferDate, plannedDate, estimatedMinutes, tags, note, parentTaskId, subtaskCount, sequential, isRecurring, recurrence, repetitionMethod, repeatSummary, nextDueDate, nextDeferDate, nextPlannedDate, catchUpAutomatically, creationDate, modificationDate, completionDate, droppedDate.

Key fields:

  • available -- true when actionable (accounts for inherited status from containers)

  • repeatSummary -- human-readable recurrence; always use this for display, don't parse RRULE

  • repetitionMethod -- "fixed" (original schedule), "start_after_completion" (defer shifts), "due_after_completion" (due shifts)

  • catchUpAutomatically -- recurring only; true = one catch-up occurrence, false = each missed interval spawns its own

  • Date fields are effective (include inherited from project). Next-occurrence fields populated only for recurring tasks.

  • Tasks inherit tags from their parent project. A task showing a tag it wasn't explicitly assigned has inherited it -- this is expected, not a bug.

Inputs: task_id, parent_task_id, include_full_notes, project_id, +37 more. Returns: result

reorder_projectA

Move a project before or after another project within the same folder.

  • project_id: str (required)

  • before_project_id: str

  • after_project_id: str

Exactly one of before/after required.

Inputs: project_id (required), before_project_id, after_project_id. Returns: result

reorder_taskA

Move a task before or after another task within the same project/level.

  • task_id: str (required)

  • before_task_id: str -- place before this task

  • after_task_id: str -- place after this task

Exactly one of before/after required. In sequential projects, order = dependencies.

Inputs: task_id (required), before_task_id, after_task_id. Returns: result

set_focusA

Focus on projects/folders, or clear focus. Does not support tasks or tags.

  • item_ids: str | list[str] -- omit or empty to clear

  • item_types: str | list[str] -- "project" or "folder"

Inputs: item_ids, item_types. Returns: result

switch_perspectiveC

Switch front window to a perspective.

  • perspective_name: str (required)

Inputs: perspective_name (required). Returns: result

update_foldersA

Update one or more folders. Each item has id (required) plus fields to change.

Parameters (per item):

  • id: str (required)

  • name: str

  • status: str -- "active" or "dropped"

Inputs: folders (required). Returns: result

update_projectsA

Update one or more projects. Each item has id (required) plus fields to change.

Parameters (per item):

  • id: str (required)

  • project_name, note, folder_path: str -- note: replaces rich text

  • project_type: str; sequential: bool (deprecated)

  • status: str -- "active", "on_hold", "done", "dropped"

  • review_interval_value: int + review_interval_unit: str ("day"/"week"/"month"/"year"); review_interval_weeks: int (deprecated)

  • last_reviewed: str -- ISO or "now" (recalculates next_review_date from review interval)

  • next_review_date: str -- set AFTER last_reviewed to override the calculated date

  • completed_by_children: bool

  • due_date, defer_date, planned_date: str -- ISO or "" to clear

  • flagged: bool

  • estimated_minutes: int

  • tags: list[str] -- full replacement (conflicts with add_tags/remove_tags)

  • add_tags, remove_tags: list[str]

  • recurrence: str -- RRULE or "" to clear; repetition_method: str -- "fixed", "start_after_completion", "due_after_completion"

Inputs: projects (required). Returns: result

update_tagsB

Update one or more tags. Each item has id (required) plus fields to change.

Parameters (per item):

  • id: str (required)

  • name, status: str -- status: "active", "on_hold", "dropped"

  • children_are_mutually_exclusive: bool

  • parent_tag: str -- move to parent by name, "" for top level

Inputs: tags (required). Returns: result

update_tasksA

Update one or more tasks. Each item has id (required) plus fields to change.

Parameters (per item):

  • id: str (required)

  • task_name, project_id, parent_task_id, note: str

  • due_date, defer_date, planned_date: str -- ISO or "" to clear

  • flagged, completed: bool -- completed=True on recurring task creates next occurrence

  • status: str -- "dropped" (prefer completed: bool for completion)

  • tags: list[str] -- full replacement (conflicts with add_tags/remove_tags)

  • add_tags, remove_tags: list[str]

  • estimated_minutes: int

  • recurrence: str -- RRULE or "" to clear; repetition_method: str

  • sequential: bool; completed_by_children: bool

Inputs: tasks (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool targets a distinct entity or action (folders, projects, tags, tasks, focus, perspectives) with clear CRUD separation. No two tools have overlapping purposes.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern, using plural for collections (create_folders, get_projects) and singular for singular concepts (get_focus, switch_perspective). No mixing of conventions.

    Tool Count4/5

    21 tools is slightly above the typical range but well-justified by the domain's complexity, covering multiple entities and operations like reordering and focus management. Still feels well-scoped without redundancy.

    Completeness4/5

    CRUD operations for all main entities exist, plus focus and perspective management. Minor gaps like perspective CRUD or advanced note handling are absent but core task management workflows are fully covered.

    Maintenance

    ActivityInactive
    ResponsivenessMostly unanswered

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables AI-powered task management in OmniFocus with support for project reviews, planned dates, repeating tasks, custom perspectives, hierarchical subtasks, and advanced filtering. Perfect for Claude AI integration with comprehensive CRUD operations for tasks, projects, and folders.
      31
      3
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      A comprehensive MCP server for OmniFocus 4 on macOS featuring 34 tools for task management, project organization, and advanced filtering. It enables full CRUD operations for tasks, projects, folders, and tags while supporting custom perspectives and complex repetition rules.
      53
      6
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Gives MCP-compatible AI assistants full, typed access to OmniFocus on macOS, enabling task management, project manipulation, inbox processing, and more via natural language.
      100
      27 npm
      2
      MIT