OmniFocus MCP Server

A Model Context Protocol (MCP) server for integrating OmniFocus with Claude Desktop. This server provides Claude with access to your OmniFocus tasks and projects, enabling AI-powered task management and weekly reviews.

Features

🎯 OmniFocus Integration - Access tasks and projects from OmniFocus
🔧 Active Task Filtering - Get only uncompleted tasks, excluding templates and system items
🚀 TypeScript + MCP SDK - Type-safe and maintainable
🔒 Secure Automation - Uses official Omni Automation JavaScript API
📱 Claude Desktop Ready - Works seamlessly with Claude Desktop

Current Tools

`omnifocus:get_all_tasks`

Retrieve all tasks from OmniFocus with filtering options:

includeCompleted (boolean) - Include completed tasks (default: false)
limit (number) - Maximum number of tasks to return (default: 100)

`omnifocus:get_active_tasks`

Retrieve only active (uncompleted) tasks, automatically filtering out:

Tasks from "Templates" folders
Tasks containing template placeholders («, »)
Tasks with synced preferences markers (⚙️)

`omnifocus:get_projects`

Retrieve all active projects from OmniFocus.

Prerequisites

macOS with OmniFocus installed
Node.js 23.10.0 or higher
Claude Desktop application
Automation permissions for OmniFocus

Installation

Clone the repository:

git clone https://github.com/mdoel/omnifocus-mcp
cd omnifocus-mcp

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Configure Claude Desktop:

Add this to your Claude Desktop MCP configuration:
```
{
  "mcpServers": {
    "omnifocus": {
      "command": "/path/to/omnifocus/run-server.sh",
      "args": []
    }
  }
}
```
Important: Replace /path/to/omnifocus/ with the actual path to your project directory.
Grant automation permissions:

The first time you run the server, macOS will prompt you to grant automation permissions for OmniFocus. Click "Allow" when prompted.

Note: If you encounter permission issues, you may need to temporarily uncomment the osascript lines in run-server.sh to trigger the permission dialog. After granting permissions, comment those lines out again to avoid the dialog on every startup.
Restart Claude Desktop to load the new MCP server.

Usage

Once configured, you can ask Claude to:

"Get all my active tasks from OmniFocus"
"Show me my projects"
"What tasks do I have for today?"
"Help me with my weekly review"

Architecture

Core Components

OmniFocusClient - Handles communication with OmniFocus via Omni Automation
OmniFocusJXA - Utility for building and executing JXA scripts
OmniFocusMCPServer - Main MCP server implementation

Directory Structure

src/
├── index.ts              # Main entry point
├── server.ts             # MCP server implementation
├── omnifocus/
│   ├── client.ts         # OmniFocus automation client
│   └── omnifocus-jxa.ts  # JXA script utilities
└── types/
    └── omnifocus.ts      # TypeScript definitions

Development

Building

# Build the project
npm run build

# Watch mode for development
npm run dev

Testing

You can test the server locally:

# Test with command line arguments
node dist/index.js all        # Get all tasks
node dist/index.js active     # Get active tasks only
node dist/index.js projects   # Get projects only

Testing OmniFocus Automation

Test OmniFocus automation directly:

# Test basic connection
osascript -l JavaScript -e "Application('OmniFocus').running()"

# Test task retrieval
osascript -l JavaScript -e "
const app = Application('OmniFocus');
const doc = app.defaultDocument;
const tasks = doc.flattenedTasks();
console.log('Found ' + tasks.length + ' tasks');
"

Troubleshooting

Server Connection Issues

If Claude Desktop can't connect to the server:

Check the script path in your Claude Desktop configuration
Verify permissions - ensure the run-server.sh script is executable:
```
chmod +x run-server.sh
```
Check Node.js installation - ensure Node.js 23.10.0+ is installed
Review logs - check Claude Desktop's MCP server logs for error messages

Permission Issues

If you get automation permission errors:

Open System Preferences > Security & Privacy > Privacy
Select Automation from the left sidebar
Find your terminal/shell and check OmniFocus
Restart your terminal and try again

OmniFocus Not Found

Ensure OmniFocus is installed and running
Verify the app name is "OmniFocus" (not "OmniFocus 3" or something similar)
Check that OmniFocus is not in the trash or disabled

Performance Issues

If the server is slow or times out:

The server may take time to process large OmniFocus databases
Consider using the limit parameter to reduce the number of tasks returned
Ensure OmniFocus is not performing other operations

Contributing

This project is designed to be extensible. To add new functionality:

Add new tools in the src/omnifocus/ directory
Update the server to register new tools
Test thoroughly with your OmniFocus data
Submit a pull request with clear documentation

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

Check the troubleshooting section above
Review the Claude Desktop MCP documentation
Open an issue in this repository