https://github.com/uthark/omnifocus-mcp
MCP for Omnifocus
https://github.com/uthark/omnifocus-mcp
claude-mcp gtd mcp mcp-server mcp-tool omnifocus
Last synced: 7 days ago
JSON representation
MCP for Omnifocus
- Host: GitHub
- URL: https://github.com/uthark/omnifocus-mcp
- Owner: uthark
- Created: 2026-04-23T06:53:33.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-29T03:09:18.000Z (about 1 month ago)
- Last Synced: 2026-05-29T05:10:24.258Z (about 1 month ago)
- Topics: claude-mcp, gtd, mcp, mcp-server, mcp-tool, omnifocus
- Language: TypeScript
- Homepage:
- Size: 190 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# omnifocus-mcp
MCP server for OmniFocus — enables AI assistants to manage tasks, projects, tags, and run GTD weekly reviews via the Model Context Protocol.
## Requirements
- macOS with OmniFocus installed
- Node.js 18+
## Setup
```bash
npm install
npm run build
```
Add to `.mcp.json` (project or `~/.claude/settings.json`):
```json
{
"mcpServers": {
"omnifocus": {
"command": "node",
"args": ["/path/to/omnifocus-mcp/dist/index.js"]
}
}
}
```
## Tools (36 total)
### Inbox
- **get_inbox_tasks** — List tasks from system, private, or work inbox (paginated, excludes completed by default)
- **process_inbox_task** — Move task to project, assign tags/dates/flags
- **quick_entry** — Create a new task in inbox or directly in a project
### Tasks
- **get_task** — Fetch a single task by ID
- **complete_task** — Mark task as completed
- **uncomplete_task** — Reopen a completed task
- **delete_task** — Delete a task
- **update_task** — Modify name, note, tags, dates, flagged, completed status
- **create_subtasks** — Break a task into subtasks
- **search_tasks** — Search incomplete tasks by name
### Projects
- **get_projects** — List projects filtered by status, optionally scoped to a folder
- **get_project_by_name** — Look up a project ID by name
- **get_project_tasks** — List tasks within a project (paginated)
- **create_project** — Create project with optional folder, tags, review interval, and initial tasks
- **update_project** — Change status, review interval, name, note
- **convert_task_to_project** — Promote a task to a project, preserving name/note/tags
### Folders
- **get_folders** — List folders (areas of responsibility) with active project counts and parent IDs
- **create_folder** — Create a folder, optionally nested inside a parent
- **update_folder** — Rename a folder
- **move_project** — Move a project into a different folder
- **delete_folder** — Delete a folder (refuses if it contains projects)
### Tags
- **get_tags** — List tags (with limit)
- **create_tag** — Create tag (supports nesting via parent tag ID)
- **update_tag** — Rename a tag and/or reparent it (pass empty parentTagId to move to document root)
- **delete_tag** — Delete a tag by ID (refuses if it has child tags; tasks are untagged, not deleted)
### Review
- **get_projects_due_for_review** — Projects past their review date
- **get_review_digest** — One row per project with stall / next-action (Planned) / deadline / last-activity signals; `scope=due` or `all-active`, optional `folderId`, `onlyStalled`, pagination — the engine for weekly review and the one-time backlog pass
- **mark_project_reviewed** — Reset review timer
- **batch_mark_reviewed** — Reset review timers for many projects in one call
- **get_stale_tasks** — Tasks in a project not modified for N days
- **get_overdue_tasks** — Tasks past due date
- **get_forecast** — Tasks due in the next N days
- **get_completed_tasks** — Tasks completed since a given date
- **get_flagged_tasks** — List all flagged incomplete tasks (your "hot list")
- **get_available_tasks** — List actionable tasks in a project (not blocked, not deferred)
- **get_tasks_by_tag** — List incomplete tasks matching any of the given tags (e.g., @waiting_for, @errands); `sortByAge`/`minAgeDays` surface aging commitments with a `daysWaiting` field; `folderId` (optional) restricts to tasks whose project lives in a specific folder (area of responsibility), keeping work and personal commitment reviews separate — mirrors `get_review_digest`'s `folderId`
## Response shape
Tool responses are returned as single-line JSON with unset/empty fields omitted to reduce token usage. Specifically: `null`, `undefined`, `""`, `[]`, and empty objects are stripped from response payloads. `false` and `0` are preserved (they carry real values). Consumers should treat absent keys as unset — for example, a task with no due date will have no `dueDate` key at all rather than `dueDate: null`.
## Development
```bash
npm run dev # watch mode
npm test # run tests
npm run build # compile TypeScript
```