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

• Examples
• Install
• Requirements
• Security
• Tools
• Resources
• Prompts
• Troubleshooting
• Development
• License

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)

Projects (11)

Folders (5)

Tags (5)

Perspectives (2)

Database (5)

Resources

Prompts

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