OmniFocus MCP Server

An MCP (Model Context Protocol) server implementation that provides programmatic access to the OmniFocus task management application on macOS. This server enables AI assistants to interact with a user's OmniFocus data through natural language commands.

Features

• Retrieve tasks based on various criteria (project, tag, due date, etc.)
• Create, modify, and complete tasks
• Manage projects and tags
• Support for TaskPaper format import/export
• Daily overviews and summaries
• Advanced filtering and querying capabilities
• Locale-independent date handling for international users
• Docker containerization for flexible deployment
• Claude Desktop integration for natural language task management

Requirements

• macOS (latest version recommended)
• Node.js (v18 or later)
• OmniFocus for Mac (latest version recommended)
• MCP SDK

Installation

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Standard Configuration

Add the following to your MCP settings file:

{
 "mcpServers": {
 "omnifocus": {
 "command": "node",
 "args": ["/path/to/omnifocus-mcp-server/build/index.js"],
 "env": {},
 "disabled": false,
 "autoApprove": []
 }
 }
}

Claude Desktop Configuration

For Claude Desktop integration, use:

{
 "mcpServers": {
 "omnifocus": {
 "command": "node",
 "args": ["/path/to/omnifocus-mcp-server/scripts/real-mcp-server.js"],
 "env": {},
 "disabled": false,
 "autoApprove": []
 }
 }
}

You can use the provided installation script for automatic setup:

./scripts/install-claude-desktop.sh

Docker Configuration

For Docker deployment, use:

{
 "mcpServers": {
 "omnifocus": {
 "command": "docker",
 "args": ["exec", "-i", "omnifocus-mcp", "node", "/app/build/index.js"],
 "env": {},
 "disabled": false,
 "autoApprove": []
 }
 }
}

Usage

The OmniFocus MCP Server provides the following tools and resources:

Tools

• get_tasks: Retrieve tasks based on specified criteria
• create_task: Create a new task with specified attributes
• update_task: Modify an existing task
• complete_task: Mark a task as complete
• delete_task: Delete a specified task
• get_projects: Retrieve projects and their structure
• create_project: Create a new project
• update_project: Modify an existing project
• get_tags: Retrieve available tags
• create_tag: Create a new tag
• check_omnifocus_status: Check if OmniFocus is running
• get_forecast: Get tasks due in the coming days

Resources

• omnifocus://tasks/{id}: Access specific task details
• omnifocus://projects/{id}: Access specific project details
• omnifocus://tags/{id}: Access specific tag details
• omnifocus://perspectives/{id}: Access specific perspective details
• omnifocus://daily: Access daily task summary
• omnifocus://forecast: Access forecast view data
• omnifocus://flagged: Access flagged items
• omnifocus://search?q={query}: Search tasks with a query string
• omnifocus://due/{date}: Access tasks due on a specific date

Date Handling

The OmniFocus MCP Server includes robust locale-independent date handling:

• All dates use ISO format (YYYY-MM-DD) in the API
• Dates are correctly interpreted regardless of system locale
• Reliable date handling for due dates and defer dates
• Comprehensive error handling for date parsing failures

For more details, see the Date Handling Documentation.

Development

Project Structure

omnifocus-mcp-server/
├── src/ # Source code
│ ├── index.ts # Entry point
│ ├── server.ts # Server implementation
│ ├── tools/ # Tool implementations
│ ├── resources/ # Resource implementations
│ ├── applescript/ # AppleScript utilities
│ ├── utils/ # Utility functions
│ │ └── dateUtils.js # Date handling utilities
│ └── types/ # TypeScript type definitions
├── build/ # Compiled JavaScript
├── tests/ # Test files
├── scripts/ # Utility scripts
│ ├── real-mcp-server.js # Claude Desktop integration
│ ├── test-date-utils.js # Date utilities testing
│ └── ... # Other utility scripts
├── docs/ # Documentation
├── docker/ # Docker configuration
├── tsconfig.json # TypeScript configuration
├── package.json # Project metadata and dependencies
└── README.md # Project documentation

Development Workflow

• Code in TypeScript
• Compile with npm run build
• Run with npm start
• Test with npm test
• Lint with npm run lint

Docker Support

Docker support is fully implemented. See Docker Setup for detailed instructions on running the OmniFocus MCP Server in a Docker container.

Claude Desktop Integration

The OmniFocus MCP Server includes special integration with Claude Desktop. See Claude Desktop Integration for detailed instructions.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Björn Schotte bjoern.schotte@mayflower.de