OmniFocus MCP Server

An MCP server that lets AI assistants read and write your OmniFocus database. Talk to Claude (or any MCP client) in natural language and it handles the OmniFocus automation for you.

Personal Project Notice: A hobby project for my workflow automation. MIT licensed -- use or adapt freely, but provided as-is.

What You Can Do

Once configured, talk to your assistant naturally:

• "What do I need to do today?"
• "Show me everything that's overdue"
• "Add 'Call dentist' to my inbox, due Friday"
• "Create a project for the kitchen remodel with these tasks..."
• "I just finished a meeting, here are my notes..." (parses into tasks)
• "How's my weekly review looking?"

The server exposes four tools that cover the full OmniFocus API:

Tool	Purpose	Operations
omnifocus_read	Query data	Tasks, projects, tags, perspectives, folders, export
omnifocus_write	Modify data	Create, update, complete, delete, batch, tag management
omnifocus_analyze	Analytics	Productivity stats, velocity, patterns, workflows, reviews
system	Diagnostics	Version info, performance metrics, cache stats

Five built-in GTD prompts (weekly review, inbox processing, Eisenhower matrix, and more) are available via the MCP prompt protocol. See Getting Started for details.

Requirements

• macOS with OmniFocus 4.7+ (the server communicates with OmniFocus via Apple's automation APIs)
• Node.js 18+

Quick Start

git clone https://github.com/kip-d/omnifocus-mcp.git
cd omnifocus-mcp
npm install
npm run build

Claude Desktop

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

{
  "mcpServers": {
    "omnifocus": {
      "command": "node",
      "args": ["/absolute/path/to/omnifocus-mcp/dist/index.js"]
    }
  }
}

Claude Code

claude mcp add omnifocus -- node /absolute/path/to/omnifocus-mcp/dist/index.js

Optional: Install the GTD skill for enhanced intent recognition and workflow guidance:

ln -s /absolute/path/to/omnifocus-mcp/docs/skills/omnifocus-assistant ~/.claude/skills/omnifocus-assistant

Other Clients

Cursor, Windsurf, Cline, and Zed all support local stdio MCP servers. Use the same node dist/index.js command; refer to each client's documentation for config file location.

Remote Access (HTTP)

The server supports HTTP transport for accessing OmniFocus from another machine (e.g., via Tailscale):

node dist/index.js --http --port 3000

See the HTTP Transport Guide for setup, authentication, and client configuration.

Documentation

Audience	Document	Purpose
Users	Getting Started	First conversation, natural language
Users	Troubleshooting	Common issues and solutions
Users	Smart Capture	Parse meeting notes into tasks
Users	HTTP Transport	Remote access setup
Developers	Developer Guide	API examples, tool call formats
Developers	Architecture	JXA + OmniJS Bridge internals
Developers	API Reference	API reference versions
Developers	Patterns and Solutions	Symptom lookup, common fixes
Developers	Documentation Map	Full index of documentation

Testing

Suite	Command	Tests	Time
Unit	npm run test:unit	1634 (70 files)	~2s
Integration	npm run test:integration	73	~4 min
All	npm test	Both suites	~4 min

Integration tests require OmniFocus running on macOS and exercise real database queries. Timing scales with database size (the ~4 min figure is against a ~2,500 task database). Set DISABLE_INTEGRATION_TESTS=true to skip them.

Limitations

• macOS only -- The server communicates with OmniFocus via Apple's JXA and OmniAutomation APIs, which require macOS. Remote access from other platforms is possible via HTTP transport.

See Troubleshooting for common issues.

License

MIT License -- see LICENSE file.