Omnifocus MCP

🚀 OmniFocus MCP Server

This is a Model Context Protocol (MCP) server designed to integrate OmniFocus with Claude Desktop. It allows Claude to access your OmniFocus tasks and projects, enabling AI - powered task management and weekly reviews.

🚀 Quick Start

To quickly get started with the OmniFocus MCP Server, follow the installation steps below. After installation, you can ask Claude to perform tasks like getting active tasks or projects from OmniFocus.

✨ Features

• 🎯 OmniFocus Integration: Gain access to tasks and projects within OmniFocus.
• 🔧 Active Task Filtering: Retrieve only uncompleted tasks, excluding templates and system items.
• 🚀 TypeScript + MCP SDK: Ensures type - safety and maintainability.
• 🔒 Secure Automation: Utilizes the official Omni Automation JavaScript API.
• 📱 Claude Desktop Ready: Works seamlessly with Claude Desktop.

📦 Installation

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Configure Claude Desktop: Add the following to your Claude Desktop MCP configuration:

   {
     "mcpServers": {
       "omnifocus": {
         "command": "/path/to/omnifocus/run-server.sh",
         "args": []
       }
     }
   }
   

   ⚠️ Important Note

   Replace /path/to/omnifocus/ with the actual path to your project directory.

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

   💡 Usage Tip

   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.

6. Restart Claude Desktop to load the new MCP server.

💻 Usage Examples

Basic Usage

Once configured, you can interact with Claude using the following commands:

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

📚 Documentation

Current Tools

omnifocus:get_all_tasks

Retrieve all tasks from OmniFocus with filtering options:

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.

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');
"

🔧 Technical Details

Troubleshooting

Server Connection Issues

If Claude Desktop can't connect to the server:

1. Check the script path in your Claude Desktop configuration.
2. Verify permissions: Ensure the run-server.sh script is executable:

   chmod +x run-server.sh
   

3. Check Node.js installation: Ensure Node.js 23.10.0+ is installed.
4. Review logs: Check Claude Desktop's MCP server logs for error messages.

Permission Issues

If you get automation permission errors:

1. Open System Preferences > Security & Privacy > Privacy.
2. Select Automation from the left sidebar.
3. Find your terminal/shell and check OmniFocus.
4. 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:

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

📄 License

This project is under the MIT License. See the 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.