OmniFocus任务管理MCP服务

omnifocus-mcp

A Model Context Protocol (MCP) server that gives AI assistants access to your OmniFocus tasks and projects. Built with the official MCP SDK and macOS JavaScript for Automation (JXA).

Features

• Query tasks - retrieve incomplete tasks with defer dates, notes, and more; filter by project, tag, or flagged status
• Query completed tasks - retrieve completed tasks for a given time period with defer dates, notes, and optional project/tag filtering
• List projects - get all active projects with their incomplete task counts
• Add tasks - create tasks with optional project, due date, defer date, tags, notes, and flagged status
• Update tasks - modify name, due date, defer date, flagged status, note, and tags on existing tasks by ID
• Create projects - create new projects with optional type (parallel/sequential) and folder assignment
• Complete tasks - mark tasks as complete by ID (preferred) or exact name + project match, with safety checks
• List tags - get all tags defined in OmniFocus
• Case-insensitive filtering - flexible filtering by project (exact match) or tag (partial match)

Prerequisites

• macOS - uses osascript to communicate with OmniFocus
• OmniFocus 3 or 4 installed
• Node.js 20+

Installation

git clone https://github.com/leedoughty/omnifocus-mcp.git
cd omnifocus-mcp
npm install
npm run build

Configuration

This server works with any MCP-compatible client. Below is an example for Claude Code (~/.claude.json):

{
  "mcpServers": {
    "omnifocus": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/omnifocus-mcp/dist/index.js"]
    }
  }
}

On first use, macOS will prompt you to grant the terminal permission to control OmniFocus via System Settings > Privacy & Security > Automation.

Tools

omnifocus_get_tasks

Returns incomplete tasks from OmniFocus. Tasks inside a completed or dropped project (or under a completed or dropped parent task) are excluded, matching what OmniFocus itself shows.

Note fields are truncated to a 100-character preview by default to keep output compact; pass full_notes: true to return the complete note for every task.

Example output:

- Review pull requests
  ID: abc123DEF
  Project: Engineering
  Flagged: yes
  Due: 2026-03-15T17:00:00.000Z
  Note: Check the auth refactor PR before release
  Tags: work, code-review
- Buy biscuits
  ID: xyz789GHI
  Project: Errands
  Defer: 2026-03-16T09:00:00.000Z
  Tags: personal

omnifocus_get_completed_tasks

Returns completed tasks from OmniFocus for a given time period. Requires a since date to bound the query.

Example output:

- Review pull requests
  ID: abc123DEF
  Project: Engineering
  Completed: 2026-03-14T15:30:00.000Z
  Note: Check the auth refactor PR before release
  Tags: work, code-review
- Buy biscuits
  ID: xyz789GHI
  Project: Errands
  Defer: 2026-03-10T09:00:00.000Z
  Completed: 2026-03-13T10:15:00.000Z
  Tags: personal

omnifocus_get_projects

Returns all active projects with their incomplete task counts.

Example output:

- Engineering (12 tasks)
- Errands (3 tasks)
- Home Renovation (7 tasks)

omnifocus_complete_task

Mark a task as complete in OmniFocus. Accepts a task ID (preferred) or exact task name + project. Refuses to act if multiple tasks match.

Provide either task_id, or both task_name and project.

Safety behaviour:

• No match found → returns error
• Multiple matches → returns error with count, completes nothing
• Exactly one match → completes the task and returns confirmation

omnifocus_add_task

Add a new task to OmniFocus. If no project is specified, the task goes to the Inbox.

Example output:

Created: "Buy biscuits"
ID: xyz789GHI
Project: Errands
Due: 2026-03-20T00:00:00.000Z
Tags: personal

omnifocus_update_task

Update an existing task in OmniFocus by ID. Only provided fields are changed.

Example output:

Updated: "Buy biscuits"
ID: xyz789GHI
Project: Errands
Flagged: yes
Due: 2026-03-20T00:00:00.000Z
Tags: personal, urgent

omnifocus_create_project

Create a new project in OmniFocus. Optionally set the project type and assign it to an existing folder.

Example output:

Created project: "Home Renovation"
ID: abc123DEF
Type: parallel
Folder: Personal

omnifocus_get_tags

Returns all tags from OmniFocus.

Example output:

- High Priority
- Waiting for
- Errands
- Full Focus
- Quick Wins
- On Hold

License

MIT