bruvik/omnifocus-mcp

OmniFocus MCP Server

MCP (Model Context Protocol) server that exposes OmniFocus task management to Claude Code and other MCP-compatible AI assistants via AppleScript automation.

Prerequisites

• macOS with OmniFocus installed
• Python 3.11+
• OmniFocus must be running for tasks to work

Setup

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Usage with Claude Desktop

Edit Claude Desktop's config file at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "omnifocus": {
      "command": "/path/to/omnifocus-mcp/.venv/bin/python",
      "args": ["/path/to/omnifocus-mcp/mcp_server.py"]
    }
  }
}

Replace /path/to/omnifocus-mcp with the actual path to this repository.

Restart Claude Desktop after editing the config.

Usage with Claude Code

Option 1: Add via CLI (Recommended)

# Use the venv's Python to ensure dependencies are available
claude mcp add omnifocus -- /path/to/omnifocus-mcp/.venv/bin/python /path/to/omnifocus-mcp/mcp_server.py

Replace /path/to/omnifocus-mcp with the actual path to this repository.

Option 2: Add to project config

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "omnifocus": {
      "command": "/path/to/omnifocus-mcp/.venv/bin/python",
      "args": ["/path/to/omnifocus-mcp/mcp_server.py"]
    }
  }
}

Option 3: Add to user config

Edit ~/.claude.json:

{
  "mcpServers": {
    "omnifocus": {
      "command": "/path/to/omnifocus-mcp/.venv/bin/python",
      "args": ["/path/to/omnifocus-mcp/mcp_server.py"]
    }
  }
}

Verify Installation (Claude Code)

# List configured MCP servers
claude mcp list

# Test the OmniFocus server
claude mcp get omnifocus

Available MCP Tools

Once connected, Claude Code can use these tools:

Example Prompts for Claude Code

• "Show me my flagged tasks in OmniFocus"
• "Add a task 'Review PR #123' to my Work project"
• "What's overdue in OmniFocus?"
• "Complete the task with ID xyz123"
• "Give me a summary of my tasks by project"
• "List all my folders in OmniFocus"
• "Create a new project called 'Q1 Planning' in the Work folder"
• "Create a folder called 'Personal Projects'"

HTTP Server (Alternative)

If you need a REST API instead of MCP, use the FastAPI server:

# Development mode with auto-reload
uvicorn server:app --reload

# Production mode
uvicorn server:app --host 0.0.0.0 --port 8000

HTTP Endpoints

• GET /health - Health check
• POST /mcp/list_tasks - Body: {"filter": "due_soon"|"flagged"|"inbox"}
• POST /mcp/summarize_tasks - Get task summary by project
• POST /mcp/add_task - Body: {"title": "...", "project": "..."}
• POST /mcp/get_projects - List all projects
• POST /mcp/complete_task - Body: {"task_id": "..."}

Testing AppleScripts Directly

# List available tasks (default)
osascript scripts/list_tasks_omni.applescript

# List with filter
osascript scripts/list_tasks_omni.applescript flagged
osascript scripts/list_tasks_omni.applescript due_soon
osascript scripts/list_tasks_omni.applescript all

# Add task (JSON format)
osascript scripts/add_task_omni.applescript '{"title": "Task name", "project": "Project name"}'
osascript scripts/add_task_omni.applescript '{"title": "Weekly review", "rrule": "FREQ=WEEKLY", "flagged": true}'

# Set repetition
osascript scripts/set_repetition.applescript "task-id" "FREQ=DAILY" "due"
osascript scripts/set_repetition.applescript "task-id" "none"  # Clear repetition

# Update task
osascript scripts/update_task.applescript "task-id" flag
osascript scripts/update_task.applescript "task-id" defer "2025-01-15T09:00:00"

# Get projects
osascript scripts/get_projects.applescript

# Complete task
osascript scripts/complete_task.applescript "task-id-here"

Architecture

┌──────────────┐     stdio/JSON-RPC     ┌─────────────────┐
│ Claude Code  │ ◄────────────────────► │  mcp_server.py  │
└──────────────┘                        └────────┬────────┘
                                                 │ osascript
                                                 ▼
                                        ┌─────────────────┐
                                        │   OmniFocus     │
                                        │   (AppleScript) │
                                        └─────────────────┘

• MCP Server (mcp_server.py): FastMCP-based server using stdio transport
• HTTP Server (server.py): Alternative REST API via FastAPI
• AppleScripts (scripts/): Direct OmniFocus automation
• Utilities (utils/): Python wrappers for AppleScript execution

License

GPL v3 - See file for details.

Todo

• Handle recurring events (RRULE format with set_repetition and add_task rrule param)
• Rename tasks (rename_task tool)
• Handle notes (add_task supports note parameter)
• Create task should be able to create a task in a specific project (already works)
• Move task around in the Projects hierarchy (move_task tool)
• Manipulate tags on tasks (list_tags, get/add/remove/set_task_tags)
• Logic to read, write and manipulate notes on existing tasks (get/set/append/clear_task_note)
• Folder and project hierarchy (list_folders, create_folder, create_project)
• Handle locations