Skip to main content
Glama
OmniFocus MCP Server

OmniFocus MCP Server

OmniFocus MCP

npm version License: MIT

✔️ Turn prompts into projects.

Feature-complete Model Context Protocol server for OmniFocus. Full read/write access to tasks, projects, folders, tags, and perspectives — 51 tools, 2 resources, and 3 prompts.

Uses Omni Automation (OmniJS) under the hood, executing scripts via JXA and osascript. This is why macOS is required.

Demo

Table of Contents

Related MCP server: OmniFocus Operator

Examples

"Create a project called 'Q3 Launch' in my Work folder with subtasks for design review, copy writing, and QA — all due next Friday, assigned sequentially."

"What's overdue? Flag anything due this week that isn't flagged yet."

"Move all tasks tagged 'waiting' in the 'Website Redesign' project to a new 'Blocked' project."

"Run my weekly review — go through stale projects, process inbox, and summarize what needs attention."

"How many tasks do I have tagged 'errand'? List the ones that are available."

Install

Claude Desktop

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

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

Claude Code

claude mcp add omnifocus -- npx -y omnifocus-mcp-server

Or add to .claude/settings.json:

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

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

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

Add to ~/.codeium/windsurf/mcp_config.json:

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

Add to ~/.codex/config.toml:

[mcp_servers.omnifocus]
command = "npx"
args = ["-y", "omnifocus-mcp-server"]

Add to ~/.gemini/settings.json:

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

Requirements

  • macOS (OmniFocus is macOS-only)

  • OmniFocus 4 (or OmniFocus 3 with Omni Automation support)

  • Node.js >= 18

  • Automation permission granted in System Settings > Privacy & Security > Automation

Security

This server has full read/write access to your OmniFocus database. It can create, modify, and delete tasks, projects, folders, and tags. Only connect it to AI clients and models you trust.

No data leaves your machine — all communication happens locally via osascript.

Tools

Tasks (23)

Tool

Description

list_tasks

List tasks with filters for status, flags, tags, projects, date ranges, and text search

get_task

Get task details by ID, optionally including subtask hierarchy

create_task

Create a task in inbox or a project, with tags, dates, and recurrence

update_task

Update task properties (name, note, dates, flags, recurrence)

complete_task

Mark a task as completed

uncomplete_task

Re-open a completed task

drop_task

Mark a task as dropped (cancelled)

delete_task

Permanently delete a task

move_tasks

Move tasks to a different project, parent task, or inbox

duplicate_tasks

Duplicate tasks, optionally into a different project

set_task_tags

Set, add, or remove tags on a task

add_task_notification

Add an absolute or due-relative notification

remove_task_notification

Remove a notification from a task

list_task_notifications

List all notifications on a task

append_task_note

Append text to a task's note

get_inbox_tasks

Get all inbox tasks

get_flagged_tasks

Get all available flagged tasks

get_today_completed_tasks

Get tasks completed today

get_task_count

Count tasks matching filters — use instead of list_tasks when you only need a number, not the full task data

convert_task_to_project

Convert a task into a project, preserving subtasks

batch_create_tasks

Create multiple tasks at once with subtask hierarchies

batch_complete_tasks

Complete multiple tasks at once

batch_delete_tasks

Delete multiple tasks at once

Projects (11)

Tool

Description

list_projects

List projects with filters for status, folder, and text search

get_project

Get project details by ID or name

create_project

Create a project with folder, sequential, SAL, tags, and review options

update_project

Update project properties

complete_project

Mark a project as done

drop_project

Mark a project as dropped (cancelled)

move_project

Move a project to a different folder

delete_project

Permanently delete a project

get_project_tasks

Get all tasks in a project

get_review_queue

Get projects due for review

mark_reviewed

Mark a project as reviewed

Folders (5)

Tool

Description

list_folders

List all folders

get_folder

Get folder details including child folders and projects

create_folder

Create a folder (supports nesting)

update_folder

Update folder name or status

delete_folder

Permanently delete a folder

Tags (5)

Tool

Description

list_tags

List all tags

get_tag

Get tag details including child tags

create_tag

Create a tag (supports nesting and allowsNextAction)

update_tag

Update tag properties

delete_tag

Permanently delete a tag

Perspectives (2)

Tool

Description

list_perspectives

List perspectives (built-in and/or custom)

get_perspective_tasks

Get tasks shown in a specific perspective

Database (5)

Tool

Description

get_database_summary

Get counts of inbox items, projects, tags, folders, and task statistics

search

Search across all items (tasks, projects, folders, tags) by name or note

dump_database

Dump the entire database in a single call

save_database

Explicitly save the database to disk

sync_database

Trigger an OmniFocus sync to push local changes to OmniSync and pull updates from other devices. Call once at the end of a chain of mutations. The batch_* tools also accept sync: true to run a sync automatically after the batch completes.

Resources

URI

Description

omnifocus://database/summary

Database summary with counts

omnifocus://perspectives

List of all perspectives

Prompts

Prompt

Description

weekly-review

Walk through your GTD weekly review: check projects due for review, process leftover inbox items, reassess flagged tasks, and get a structured summary. Marks projects as reviewed when done.

inbox-processing

Process inbox items one-by-one using GTD methodology — delete non-actionable items, do anything under 2 minutes, and organize the rest into projects with tags and dates.

daily-planning

Build a prioritized plan for today based on due dates, flagged items, and what you've already completed. Surfaces overdue tasks and estimates your workload.

Troubleshooting

"Not authorized" or no response from OmniFocus

Make sure Automation permissions are granted. Go to System Settings > Privacy & Security > Automation and ensure your terminal app (Terminal, iTerm, etc.) is allowed to control OmniFocus.

Changes not taking effect after rebuild

If you're developing locally, multiple MCP server processes may be running (from Claude Desktop, Claude Code, etc.). Kill them all and restart:

pkill -f "omnifocus-mcp-server"
# or if running from source:
pkill -f "omnifocus/mcp/dist/index.js"

Stale npx cache

If npx is running an old version, clear the cache:

npx clear-npx-cache
# then re-run your MCP client

OmniFocus 3 compatibility

OmniFocus 3 works if Omni Automation is enabled. Go to OmniFocus > Preferences > General and check "Omni Automation". Some features (like certain perspective types) may behave differently.

Tool calls are slow

Each tool call runs an osascript process to communicate with OmniFocus. This typically takes 200-500ms per call. Batch tools (batch_create_tasks, batch_complete_tasks, batch_delete_tasks) are much faster for bulk operations than calling individual tools in a loop.

Development

npm install
npm run build      # Compile TypeScript
npm run dev        # Run with tsx (hot reload)
npm test           # Run unit tests
npm run test:watch # Watch mode

Integration Tests

Tests against a real OmniFocus instance (creates and cleans up test items):

OMNIFOCUS_LIVE=1 npm run test:integration

Contributing

PRs welcome. Please run npm test before submitting and include tests for new tools.

License

MIT

Available Tools

51 tools
add_task_notificationC

Add a notification/reminder to a task

Inputs: taskId (required), type (required), absoluteDate, relativeOffset.

append_task_noteB

Append text to an existing task's note

Inputs: taskId (required), text (required).

batch_complete_tasksB

Complete multiple tasks at once. More efficient than completing one by one.

Inputs: taskIds (required), sync.

batch_create_tasksB

Create multiple tasks at once, with support for subtask hierarchies. Much more efficient than creating tasks one by one.

Inputs: tasks (required), projectId, projectName, parentTaskId, +1 more.

batch_delete_tasksA

Delete multiple tasks at once. More efficient than deleting one by one.

Inputs: taskIds (required), sync.

complete_projectC

Mark a project as completed (done)

Inputs: id (required).

complete_taskB

Mark a task as completed

Inputs: id (required), completionDate.

convert_task_to_projectB

Convert an existing task into a new project, preserving subtasks

Inputs: taskId (required).

create_folderB

Create a new folder in OmniFocus

Inputs: name (required), parentFolderId, parentFolderName.

create_projectB

Create a new project in OmniFocus

Inputs: name (required), note, folderId, folderName, +9 more.

create_tagB

Create a new tag in OmniFocus

Inputs: name (required), parentTagId, parentTagName, allowsNextAction, +1 more.

create_taskA

Create a new task in OmniFocus. By default creates in inbox; specify projectId or projectName to add to a project.

Inputs: name (required), note, flagged, deferDate, +8 more.

delete_folderB

Permanently delete a folder from OmniFocus

Inputs: id (required).

delete_projectB

Permanently delete a project from OmniFocus

Inputs: id (required).

delete_tagB

Permanently delete a tag from OmniFocus

Inputs: id (required).

delete_taskA

Permanently delete a task from OmniFocus

Inputs: id (required).

drop_projectC

Mark a project as dropped (cancelled)

Inputs: id (required).

drop_taskA

Mark a task as dropped (cancelled)

Inputs: id (required).

dump_databaseA

Dump the entire OmniFocus database including inbox, projects, folders, tags, and perspectives in a single call. Essential for getting full context.

Inputs: includeCompleted, maxDepth, hideRecurringDuplicates.

duplicate_tasksA

Duplicate one or more tasks, optionally into a different project

Inputs: taskIds (required), projectId, projectName.

get_database_summaryA

Get a summary of the OmniFocus database including counts of inbox items, projects, tags, folders, available/due-soon/overdue/flagged tasks

Inputs: no named parameters.

get_flagged_tasksC

Get all available flagged tasks

Inputs: no named parameters.

get_folderA

Get detailed information about a folder including its child folders and projects

Inputs: id (required).

get_inbox_tasksA

Get all tasks currently in the OmniFocus inbox (not yet assigned to a project)

Inputs: no named parameters.

get_perspective_tasksA

Get tasks shown in a specific custom perspective. Built-in perspectives (Inbox, Forecast, etc.) are not supported — use dedicated tools instead.

Inputs: name (required).

get_projectA

Get detailed information about a specific project by ID or name

Inputs: idOrName (required).

get_project_tasksB

Get all tasks belonging to a specific project

Inputs: projectId (required), includeCompleted.

get_review_queueA

Get projects that are due for review

Inputs: no named parameters.

get_tagB

Get detailed information about a tag including its child tags

Inputs: id (required).

get_taskA

Get detailed information about a specific task by its ID, optionally including subtask hierarchy

Inputs: id (required), includeChildren, maxDepth.

get_task_countA

Get count of tasks matching filters without fetching full data. Faster than list_tasks when you only need the count.

Inputs: completed, flagged, available, inInbox, +11 more.

get_today_completed_tasksB

Get all tasks completed today

Inputs: no named parameters.

list_foldersB

List all folders in OmniFocus

Inputs: no named parameters.

list_perspectivesA

List custom perspectives in OmniFocus. Built-in perspectives (Inbox, Projects, Tags, Forecast, Flagged, Review, Nearby) are not enumerable via the API — use dedicated tools instead (get_inbox_tasks, get_flagged_tasks, get_review_queue, list_projects, list_tags, or list_tasks with date filters for Forecast).

Inputs: no named parameters.

list_projectsB

List projects from OmniFocus with optional filters for status, folder, and text search

Inputs: status, folderId, folderName, search, +2 more.

list_tagsA

List all tags in OmniFocus

Inputs: no named parameters.

list_task_notificationsB

List all notifications/reminders on a task

Inputs: taskId (required).

list_tasksA

List tasks from OmniFocus with optional filters for status, flags, tags, projects, date ranges, and text search

Inputs: completed, flagged, available, inInbox, +13 more.

mark_reviewedB

Mark a project as reviewed, advancing its next review date

Inputs: id (required).

move_projectB

Move a project to a different folder

Inputs: projectId (required), folderId (required).

move_tasksA

Move one or more tasks to a different project or parent task. Omit destination to move to inbox.

Inputs: taskIds (required), projectId, projectName, parentTaskId.

remove_task_notificationB

Remove a specific notification from a task

Inputs: taskId (required), notificationId (required).

save_databaseA

Explicitly save the OmniFocus database to disk

Inputs: no named parameters.

set_task_tagsB

Set, add, or remove tags on a task

Inputs: taskId (required), tagNames (required), mode (required).

sync_databaseA

Trigger an OmniFocus sync to push local changes to OmniSync and pull updates from other devices. CALL THIS ONCE at the end of any session that mutated data — especially after batch_create_tasks, batch_complete_tasks, batch_delete_tasks, or any sequence of multiple create/update/delete/move operations. Do NOT call after every individual mutation; sync once at the end of the chain. Returns immediately while sync runs in the background.

Inputs: no named parameters.

uncomplete_taskA

Mark a completed task as incomplete (re-open it)

Inputs: id (required).

update_folderB

Update a folder's properties

Inputs: id (required), name, status.

update_projectB

Update properties of an existing project

Inputs: id (required), name, note, status, +8 more.

update_tagB

Update a tag's properties

Inputs: id (required), name, allowsNextAction, status.

update_taskB

Update properties of an existing task

Inputs: id (required), name, note, flagged, +7 more.

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 51 tools

    Disambiguation5/5

    Each tool targets a specific action on a specific entity (task, project, folder, tag, notification) with clear descriptions. Even related tools like 'complete_task' and 'batch_complete_tasks' are easily distinguished by scope and intent.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., create_task, delete_folder, sync_database) with no mixing of styles. The naming is predictable and clear.

    Tool Count2/5

    With 51 tools, the set is extremely large. While the domain (OmniFocus) is complex, many tools are batch variants or duplicate operations (e.g., complete_task and batch_complete_tasks). This exceeds typical well-scoped tool sets and may overwhelm agents.

    Completeness5/5

    The tool set covers all major CRUD operations for tasks, projects, folders, and tags, plus batch operations, notifications, tags, search, sync, and review. There are no obvious gaps for managing an OmniFocus database.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • 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
      B
      maintenance
      An MCP server that enables AI assistants to interact with OmniFocus on macOS via JXA, supporting task, project, folder, tag, perspective, and search operations.
      31
      25 npm
      MIT