OmniFocus MCP Server
Click on "Deploy 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 Server Create a task 'Review Q3 budget' due Friday in Work folder."
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.
OmniFocus MCP
✔️ 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.

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-serverOr 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 with filters for status, flags, tags, projects, date ranges, and text search |
| Get task details by ID, optionally including subtask hierarchy |
| Create a task in inbox or a project, with tags, dates, and recurrence |
| Update task properties (name, note, dates, flags, recurrence) |
| Mark a task as completed |
| Re-open a completed task |
| Mark a task as dropped (cancelled) |
| Permanently delete a task |
| Move tasks to a different project, parent task, or inbox |
| Duplicate tasks, optionally into a different project |
| Set, add, or remove tags on a task |
| Add an absolute or due-relative notification |
| Remove a notification from a task |
| List all notifications on a task |
| Append text to a task's note |
| Get all inbox tasks |
| Get all available flagged tasks |
| Get tasks completed today |
| Count tasks matching filters — use instead of |
| Convert a task into a project, preserving subtasks |
| Create multiple tasks at once with subtask hierarchies |
| Complete multiple tasks at once |
| Delete multiple tasks at once |
Projects (11)
Tool | Description |
| List projects with filters for status, folder, and text search |
| Get project details by ID or name |
| Create a project with folder, sequential, SAL, tags, and review options |
| Update project properties |
| Mark a project as done |
| Mark a project as dropped (cancelled) |
| Move a project to a different folder |
| Permanently delete a project |
| Get all tasks in a project |
| Get projects due for review |
| Mark a project as reviewed |
Folders (5)
Tool | Description |
| List all folders |
| Get folder details including child folders and projects |
| Create a folder (supports nesting) |
| Update folder name or status |
| Permanently delete a folder |
Tags (5)
Tool | Description |
| List all tags |
| Get tag details including child tags |
| Create a tag (supports nesting and allowsNextAction) |
| Update tag properties |
| Permanently delete a tag |
Perspectives (2)
Tool | Description |
| List perspectives (built-in and/or custom) |
| Get tasks shown in a specific perspective |
Database (5)
Tool | Description |
| Get counts of inbox items, projects, tags, folders, and task statistics |
| Search across all items (tasks, projects, folders, tags) by name or note |
| Dump the entire database in a single call |
| Explicitly save the database to disk |
| 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 |
Resources
URI | Description |
| Database summary with counts |
| List of all perspectives |
Prompts
Prompt | Description |
| 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. |
| 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. |
| 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 clientOmniFocus 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 modeIntegration Tests
Tests against a real OmniFocus instance (creates and cleans up test items):
OMNIFOCUS_LIVE=1 npm run test:integrationContributing
PRs welcome. Please run npm test before submitting and include tests for new tools.
License
MIT
Available Tools
51 toolsadd_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.
searchB
Search across all OmniFocus items (tasks, projects, folders, tags) by name or note content
Inputs: query (required), limit.
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
Scored across 51 tools
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.
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.
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.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseBqualityCmaintenanceA 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.536MIT
- FlicenseNot gradedqualityBmaintenanceA production-grade MCP server that exposes OmniFocus as structured task infrastructure for AI agents, enabling read, write, and filter operations on tasks and projects via natural language.11-
- AlicenseNot gradedqualityDmaintenanceMCP server that gives AI assistants full control over OmniFocus on macOS, including tasks, projects, tags, folders, perspectives, forecast, notifications, and review workflows.44MIT
- AlicenseAqualityBmaintenanceAn MCP server that enables AI assistants to interact with OmniFocus on macOS via JXA, supporting task, project, folder, tag, perspective, and search operations.3125 npmMIT