mcp-omnifocus by BjoernSchotte - MCP Server

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

Clone the repository:

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

Install dependencies:
```
npm install
```
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 .

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 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 for detailed instructions.

License

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