Omnifocus
Overview
OmniFocus MCP Server
An MCP server that gives AI assistants full access to OmniFocus via Omni Automation. 41 tools for tasks, projects, folders, tags, subtask hierarchies, notifications, attachments, analytics, and data export.
How it works
The server runs osascript -l JavaScript to call app.evaluateJavascript(), which executes scripts inside OmniFocus's native Omni Automation engine. No direct database access — all interaction goes through the official API.
Installation
git clone https://github.com/alexhanna/omnifocus-mcp.git
cd omnifocus-mcp
npm install
npm run build
MCP client configuration
Add the server to your MCP client's configuration. The server entry looks like:
{
"mcpServers": {
"omnifocus": {
"command": "node",
"args": ["/path/to/omnifocus-mcp/dist/index.js"],
"env": {
"LOG_LEVEL": "info"
}
}
}
}
Where this lives depends on your client:
- Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json - Claude Code:
~/.claude/settings.jsonor project.mcp.json - Other MCP clients: consult your client's documentation for server configuration
Requirements
- macOS (required for osascript)
- OmniFocus 4.6+ installed
- Node.js 18+
- macOS automation permission for OmniFocus (granted on first use — see docs/PERMISSIONS.md)
Tools
Tasks (7 tools)
| Tool | Description |
|---|---|
list_tasks | Filter by completion, flags, project, tags, dates, search, inbox, availability. Cached 30s. |
get_task_count | Count matching tasks without returning data. |
todays_agenda | Tasks due today, overdue, or flagged. |
create_task | Create task with name, note, flags, dates, tags, project, estimated time. |
update_task | Modify any task property. Move between projects. |
complete_task | Mark task completed. |
delete_task | Remove task. |
Projects (5 tools)
| Tool | Description |
|---|---|
list_projects | Filter by status, flags, folder. Cached 5min. |
create_project | Create with folder placement (auto-creates folder if needed). |
update_project | Change properties, move between folders. |
complete_project | Mark project done (optionally complete all tasks). |
delete_project | Remove project. |
Folders (6 tools)
| Tool | Description |
|---|---|
list_folders | List with nesting depth and status filter. |
create_folder | Create folder, optionally nested. |
update_folder | Rename, change status. |
delete_folder | Drop folder (optionally move contents first). |
get_folder_contents | List projects and subfolders in a folder. |
move_to_folder | Move project or folder into a different folder. |
Task Hierarchies (5 tools)
| Tool | Description |
|---|---|
get_task_hierarchy | Get task with full subtask tree (configurable depth). |
create_subtask | Create child task with position control. |
move_task | Move task to different parent or project root. |
set_task_ordering | Set sequential/parallel and completedByChildren. |
list_subtasks | List direct children of a task. |
Tags (2 tools)
| Tool | Description |
|---|---|
list_tags | List all tags. Optional (expensive) usage statistics. |
manage_tags | Create, rename, delete, merge tags. Supports nested tags via parentTag. |
Notifications (4 tools)
| Tool | Description |
|---|---|
list_notifications | List all notifications on a task. |
add_notification | Add absolute (date) or relative (offset from due) notification. |
remove_notification | Remove notification by index. |
clear_notifications | Remove all notifications from a task. |
Attachments (4 tools)
| Tool | Description |
|---|---|
list_attachments | List attachment metadata and linked files on a task. |
add_linked_file | Link a file:// path to a task. |
remove_attachment | Remove embedded attachment by index. |
remove_linked_file | Unlink a file reference. |
Analytics (3 tools)
| Tool | Description |
|---|---|
get_productivity_stats | Completion rates, time distribution. Group by project/tag/day/week. |
get_task_velocity | Task throughput over day/week/month. |
analyze_overdue_tasks | Overdue patterns grouped by project/tag/age/priority. |
Recurring Tasks (2 tools)
| Tool | Description |
|---|---|
analyze_recurring_tasks | List recurring tasks with frequency and due dates. |
get_recurring_patterns | Statistics about recurring task frequencies. |
Export (3 tools)
| Tool | Description |
|---|---|
export_tasks | Export tasks as JSON or CSV with field selection. |
export_projects | Export projects with optional statistics. |
bulk_export | Export all data (tasks, projects, tags) to files. |
Architecture
src/
├── cache/ # TTL-based caching (30s tasks, 5min projects, 1h analytics)
├── omnifocus/
│ ├── OmniAutomation.ts # Bridge: osascript → evaluateJavascript()
│ ├── scripts/ # Omni Automation script templates
│ └── types.ts # Type definitions
├── tools/ # 41 MCP tools in 10 domain directories
│ ├── tasks/ ├── projects/ ├── folders/
│ ├── hierarchy/ ├── tags/ ├── notifications/
│ ├── attachments/ ├── analytics/ ├── recurring/
│ └── export/
├── utils/ # Logging, permission checking
└── index.ts # Server entry point
Script execution flow:
- Tool calls
omniAutomation.buildScript(template, params)— replaces{{placeholders}}withJSON.stringify-escaped values wrapScript()wraps the script in a try/catch IIFE- The wrapped script is
JSON.stringify-escaped again and passed toapp.evaluateJavascript() osascript -l JavaScriptruns the outer JXA wrapper- JSON result is parsed and returned through MCP
Known limitations
- No recurring task creation — can read recurring patterns but cannot create repeat rules
- No perspective management — Omni Automation API is read-only for perspectives
- No location-based tags — must be set manually in OmniFocus UI
add_linked_fileonly acceptsfile://URLs — OmniFocus rejects http/https- MCP server caches builds — Claude Code must restart to pick up
npm run buildchanges - No review/perspective management via automation
Development
npm run build # Compile TypeScript
npm run dev # Watch mode
npm test # Unit tests (vitest)
npm run typecheck # Type check without building
License
MIT — see LICENSE
Server Config
{
"mcpServers": {
"omnifocus": {
"command": "node",
"args": [
"/path/to/omnifocus-mcp/dist/index.js"
],
"env": {
"LOG_LEVEL": "info"
}
}
}
}Project Info
Created At
4 months agoUpdated At
4 months agoAuthor Name
alexhannaonlineStar
-Language
-License
-Tags
Recommend Servers
View AllMcp Server Chatsum
@chatmcp
summarize chat message
typescript
a year ago
Gpt Scrambler
2 days ago
Test
@modelcontextprotocol
test
6 months ago