OmniFocus MCP Enhanced

You can run and use the OmniFocus MCP Enhanced server to connect OmniFocus with MCP clients, enabling native custom perspectives, hierarchical task displays, and AI-assisted workflows. This server exposes extensive task management capabilities and ready-made tools to automate, filter, and orchestrate your OmniFocus data through MCP clients.

How to use

You will interact with the MCP server through an MCP client that communicates over the MCP protocol. Use the client to create, read, update, and delete tasks and projects, access built-in perspectives, and leverage the native custom perspective features for hierarchical task displays. You can also batch operate on multiple tasks, filter tasks with complex criteria, and integrate Claude AI to optimize workflows.

How to install

Prerequisites you need before installation:

Install using the quick one-line command for immediate setup:

claude mcp add omnifocus-enhanced -- npx -y omnifocus-mcp-enhanced

Alternative installation methods

If you prefer alternative methods, you can upgrade/install via npm and set up a local or global instance, followed by adding the MCP with your chosen runtime command.

# Upgrade to latest
npm install -g omnifocus-mcp-enhanced@latest

# 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"

Configuration and start tips

To start using the MCP server, ensure OmniFocus is running and the MCP command is accepted by Claude. You can verify basic connectivity and test core commands like listing inbox tasks and custom perspectives.

Security and environment

Keep your API endpoints and keys secure. If you expose any environment variables for MCP operation, store them securely and limit their scope to your local or server environment.

Troubleshooting

If you encounter issues, confirm that you meet all prerequisites, including macOS compatibility, OmniFocus installation, and the proper version of Node.js. Check Claude Code MCP configuration and ensure accessibility permissions are granted where needed.

Use cases and capabilities

Leverage the MCP server to manage subtask hierarchies, access perspectives programmatically, perform advanced task filtering, and utilize AI-assisted planning for productive workflows.

Available tools

dump_database

Get a snapshot of the OmniFocus MCP database state for debugging and auditing.

add_omnifocus_task

Create tasks with optional subtasks and hierarchical relationships.

add_project

Create new projects to organize tasks under structured contexts.

remove_item

Delete tasks or projects by ID or name.

edit_item

Edit tasks or projects, including moving tasks between projects or inbox.

move_task

Move an existing task to a different project, parent task, or inbox.

batch_add_items

Bulk add multiple tasks or subtasks in a single operation.

batch_remove_items

Bulk remove multiple tasks or projects.

get_task_by_id

Query detailed information about a specific task by its ID.

get_inbox_tasks

Retrieve tasks in the Inbox perspective.

get_flagged_tasks

Retrieve tasks marked as flagged for quick review.

get_forecast_tasks

Fetch forecast data including due, deferred, and planned tasks.

get_tasks_by_tag

Filter tasks by tag with options for exact or partial matches.

filter_tasks

Apply complex combinations to create custom views.

list_custom_perspectives

List all user-defined custom perspectives with details.

get_custom_perspective_tasks

Access custom perspectives with hierarchical or flat display modes.

get_today_completed_tasks

View today's completed tasks for progress tracking.