Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@omnifocus-mcp What are my tasks for today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets AI assistants read and write your OmniFocus database. Talk to Claude (or any MCP client) in natural language and it handles the OmniFocus automation for you.
Personal Project Notice: A hobby project for my workflow automation. MIT licensed -- use or adapt freely, but provided as-is.
Once configured, talk to your assistant naturally:
"What do I need to do today?"
"Show me everything that's overdue"
"Add 'Call dentist' to my inbox, due Friday"
"Create a project for the kitchen remodel with these tasks..."
"I just finished a meeting, here are my notes..." (parses into tasks)
"How's my weekly review looking?"
The server exposes four tools that cover the full OmniFocus API:
Tool | Purpose | Operations |
| Query data | Tasks, projects, tags, perspectives, folders |
| Modify data | Create, update, complete, delete, batch, tag management |
| Analytics | Productivity stats, velocity, patterns, workflows, reviews |
| Diagnostics | Version info, performance metrics, cache stats |
Five built-in GTD prompts (weekly review, inbox processing, Eisenhower matrix, and more) are available via the MCP prompt protocol. See Getting Started for details.
Related MCP server: OmniFocus MCP Server
macOS with OmniFocus 4.7+ (the server communicates with OmniFocus via Apple's automation APIs)
Node.js 18+
git clone https://github.com/kip-d/omnifocus-mcp.git
cd omnifocus-mcp
npm install
npm run buildAdd to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"omnifocus": {
"command": "node",
"args": ["/absolute/path/to/omnifocus-mcp/dist/index.js"]
}
}
}claude mcp add omnifocus -- node /absolute/path/to/omnifocus-mcp/dist/index.jsOptional: Install the GTD skill for enhanced intent recognition and workflow guidance:
ln -s /absolute/path/to/omnifocus-mcp/docs/skills/omnifocus-assistant ~/.claude/skills/omnifocus-assistantCursor, Windsurf, Cline, and Zed all support local stdio MCP servers. Use the same node dist/index.js command; refer
to each client's documentation for config file location.
The server supports HTTP transport for accessing OmniFocus from another machine (e.g., via Tailscale):
node dist/index.js --http --port 3000See the HTTP Transport Guide for setup, authentication, and client configuration.
Audience | Document | Purpose |
Users | First conversation, natural language | |
Users | Common issues and solutions | |
Users | Parse meeting notes into tasks | |
Users | Remote access setup | |
Developers | API examples, tool call formats | |
Developers | JXA + OmniJS Bridge internals | |
Developers | API reference versions | |
Developers | Symptom lookup, common fixes | |
Developers | Full index of documentation |
Suite | Command | Tests | Time |
Unit |
| 1634 (70 files) | ~2s |
Integration |
| 73 | ~4 min |
All |
| Both suites | ~4 min |
Integration tests require OmniFocus running on macOS and exercise real database queries. Timing scales with database
size (the ~4 min figure is against a ~2,500 task database). Set DISABLE_INTEGRATION_TESTS=true to skip them.
macOS only -- The server communicates with OmniFocus via Apple's JXA and OmniAutomation APIs, which require macOS. Remote access from other platforms is possible via HTTP transport.
See Troubleshooting for common issues.
MIT License -- see LICENSE file.
Analyze OmniFocus data for insights, patterns, and specialized operations.
ANALYSIS TYPES:
productivity_stats: GTD health metrics (completion rates, velocity)
task_velocity: Completion trends over time
overdue_analysis: Bottleneck identification
pattern_analysis: Database-wide patterns (tags, projects, stale items)
workflow_analysis: Deep workflow analysis
recurring_tasks: Recurring task patterns and frequencies
parse_meeting_notes: Extract action items from meeting notes
manage_reviews: Project review operations params: { operation, projectId, reviewDate, reviewInterval }
set_schedule accepts reviewInterval: { unit: 'day'|'week'|'month'|'year', steps: positive int }
PERFORMANCE WARNINGS:
pattern_analysis on 1000+ items: ~5-10 seconds
workflow_analysis: ~3-5 seconds for comprehensive
Most others: <1 second with caching
SCOPE FILTERING:
Use dateRange for time-based analysis
Use tags/projects to focus analysis
| Name | Required | Description | Default |
|---|---|---|---|
| analysis | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent), the description adds detailed performance warnings (e.g., pattern_analysis on 1000+ items takes 5-10 seconds) and caching behavior, which is excellent for agent decision-making.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (ANALYSIS TYPES, PERFORMANCE WARNINGS, SCOPE FILTERING) and front-loads the purpose. It is reasonably concise with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (multiple analysis types, nested params) and no output schema, the description covers scope, performance, and some param details. Missing explicit output format, but still fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description partially compensates by detailing params for manage_reviews and mentioning scope filtering. However, not all analysis types' params are described, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool analyzes OmniFocus data for insights and lists specific analysis types. It is distinct from sibling tools (read/write) but does not explicitly differentiate them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use each analysis type and performance warnings, but it does not offer explicit guidance on when to avoid this tool or compare it with siblings like omnifocus_read.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query OmniFocus data with flexible filtering. Returns tasks, projects, tags, perspectives, folders, or exports.
COMMON QUERIES:
Inbox: { query: { type: "tasks", filters: { project: null } } }
Tasks in a specific project (by ID, fast): { query: { type: "tasks", filters: { projectId: "" } } }
Overdue: { query: { type: "tasks", mode: "overdue" } }
Today perspective: { query: { type: "tasks", mode: "today" } }
Flagged: { query: { type: "tasks", mode: "flagged" } }
Upcoming (7 days): { query: { type: "tasks", mode: "upcoming", daysAhead: 7 } }
Smart suggestions: { query: { type: "tasks", mode: "smart_suggest", limit: 10 } }
Count only (fast): { query: { type: "tasks", filters: { flagged: true }, countOnly: true } }
Export tasks: { query: { type: "export", exportType: "tasks", format: "json" } }
MODES (tasks queries ONLY — not valid on type:"projects"):
today: Due soon (≤3 days) OR flagged, matching OmniFocus Today perspective
overdue: Tasks past their due date
flagged: Flagged tasks
upcoming: Tasks due in next N days (set daysAhead, default 14)
inbox, available, blocked, search, smart_suggest, all
To SEARCH projects (or tasks) use filters, not mode: filters: { name: { contains: "..." } } or filters: { text: { matches: "regex" } }
FILTER OPERATORS:
tags: { any: [...] } (has any), { all: [...] } (has all), { none: [...] } (has none)
dates (dueDate, deferDate, plannedDate, added): { before: "YYYY-MM-DD" }, { after: "..." }, { between: ["...", "..."] }
text: { contains: "..." }, { matches: "regex" }
boolean: flagged, blocked, available, inInbox
logic: { OR: [...] }, { AND: [...] }, { NOT: {...} }
RESPONSE CONTROL:
Default returns minimal fields (id, name, flagged, completed, dueDate, deferDate, tags, project, available)
details: true returns all fields with full notes
fields: [...] returns exactly those fields (note truncated to 200 chars unless details: true)
ID lookup always returns all fields with full notes
fields are type-specific; requesting a field of the other type (e.g. reviewInterval on tasks) returns a guided error
fields (tasks): id, name, completed, flagged, blocked, available, estimatedMinutes, dueDate, deferDate, plannedDate, completionDate, added, modified, dropDate, note, projectId, project, tags, repetitionRule, parentTaskId, parentTaskName, inInbox
fields (projects): id, name, status, flagged, note, dueDate, deferDate, completionDate, folder, folderPath, folderId, sequential, lastReviewDate, nextReviewDate, reviewInterval, defaultSingletonActionHolder, tags, plannedDate
sort: [{ field: "dueDate", direction: "asc" }]
limit/offset: Pagination (default limit: 25, max: 500)
countOnly: true returns only count (33x faster for "how many" questions) — tasks only
COMPLETED TASKS:
Use filters: { completed: true } or filters: { status: "completed" } to query completed tasks
includeCompleted is for export operations only (type: "export"); honored by exportType: "tasks" and exportType: "all"
EXPORT TO DISK:
outputDirectory: when set with exportType: "tasks", writes tasks. to disk (raises the implicit cap to 5000); required for exportType: "all"
A response-path export (no outputDirectory) caps at 1000 by default and emits summary.truncated when the cap fires; override with limit
PERFORMANCE:
Use countOnly for counting questions
Use fields to select only needed data
Use modes instead of raw filters when available
Default queries are token-efficient (9 fields, no notes)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context: default fields, ID lookup returns full details, performance notes, and export behavior. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with sections and examples. It is front-loaded with a clear summary. A minor reduction for length, but each section earns its place given complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Highly complete: covers all aspects of usage including response control, pagination, performance, export details, and field lists. No output schema, but description sufficiently describes return behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description explains every parameter in detail: types, modes, filters, fields, sort, limit, countOnly, etc. It adds immense value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries OmniFocus data with flexible filtering, lists supported types (tasks, projects, tags, etc.), and distinguishes itself from sibling tools (omnifocus_write, omnifocus_analyze) by being read-only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides extensive, explicit guidance: common queries, modes (with constraints like 'tasks queries ONLY'), filter operators, response control, performance tips, and caveats (e.g., includeCompleted only for export). Clearly differentiates when to use modes vs filters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create, update, complete, or delete OmniFocus tasks and projects.
OPERATIONS:
create: New task/project with data
create_folder: New folder (name required, optional parentFolder for nesting)
update: Modify existing (provide id + changes; "data" accepted as an alias for "changes"; target defaults to "task" if omitted)
complete: Mark done (provide id; target defaults to "task" if omitted)
delete: Remove permanently (provide id, or its alias target_id)
batch: Multiple operations in one call
bulk_delete: Delete multiple items by IDs
tag_manage: Manage tag hierarchy (create, rename, delete, merge, nest, unnest, reparent)
FOLDER CREATION:
operation: "create_folder"
data.name: Folder name (required)
data.parentFolder: Parent folder name, path ("Parent : Child"), or ID (optional, omit for top-level)
Supports nested path lookup with " : " syntax (parent must already exist)
BATCH OPERATIONS:
operations: Array of create, update, complete, and delete operations
Execution order: creates first, then updates, completes, deletes last
Put tempId and parentTempId inside data (not at operation level)
Updates/completes can reference tempIds from creates in the same batch
createSequentially: true (respects dependencies)
returnMapping: true (returns tempId → realId map)
stopOnError: true (halt on first failure)
Example with subtasks: { "mutation": { "operation": "batch", "operations": [ { "operation": "create", "target": "task", "data": { "name": "Parent", "tempId": "p1", "project": "My Project" } }, { "operation": "create", "target": "task", "data": { "name": "Subtask", "tempId": "s1", "parentTempId": "p1" } } ] } }
REPETITION RULES (in data.repetitionRule):
frequency: "daily"|"weekly"|"monthly"|"yearly" (required)
interval: number (default 1)
method: "fixed"|"due-after-completion"|"defer-after-completion" (default "fixed")
daysOfWeek: [{ day: "SU"|"MO"|"TU"|"WE"|"TH"|"FR"|"SA", position?: number }] (for weekly)
daysOfMonth: [1-31] (for monthly, -1 = last day)
REVIEW INTERVAL (project-only, in data.reviewInterval or changes.reviewInterval):
Number of days: 7 (weekly), 14 (biweekly), 30 (monthly)
Object form: { steps: 1, unit: "weeks" } or { steps: 2, unit: "months" }
Valid units: "days", "weeks", "months", "years" (singular also accepted)
Both forms are accepted; object form matches OmniFocus read output
TAG OPERATIONS:
tags: [...] - Replace all tags
addTags: [...] - Add to existing
removeTags: [...] - Remove from existing
Nested tags use " : " path syntax: "Parent : Child : Leaf" (creates hierarchy, assigns leaf)
TAG MANAGEMENT (tag_manage operation):
create: Create new tag (tagName required). Supports " : " path syntax for nested hierarchies.
rename: Rename tag (tagName + newName required)
delete: Delete tag (tagName required)
merge: Merge source into target (tagName + targetTag required)
nest: Move tag under parent (tagName + parentTag required)
unnest: Move tag to root level (tagName required)
reparent: Move tag to different parent (tagName + parentTag required)
DATE FORMATS:
Date only: "YYYY-MM-DD" (defaults: due=5pm, defer=8am, planned=8am)
Date+time: "YYYY-MM-DD HH:mm" (local time)
Clear date: null or clearDueDate/clearDeferDate/clearPlannedDate: true
MOVE TO INBOX: Set project: null
SAFETY:
Delete is permanent - confirm with user first
Batch supports up to 100 operations
| Name | Required | Description | Default |
|---|---|---|---|
| mutation | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds detailed behavioral context: 'Delete is permanent', batch execution order, date defaults (due=5pm, defer=8am), move-to-inbox via project: null, and support for nested paths. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-organized with section headers (OPERATIONS, FOLDER CREATION, BATCH, etc.) and front-loaded with a summary. Every section is informative and necessary given the tool's complexity. It could be slightly more concise (e.g., repeating examples), but overall it is efficient for the domain.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple operations, nested parameters) and lack of output schema, the description covers inputs thoroughly, including date formats, tag management, and batch behavior. It does not describe return values, which is acceptable for a mutation tool. The description is sufficiently complete for an AI agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage (only target_id and completionDate have descriptions). The description fully compensates by explaining the mutation object structure, each operation's required/optional fields, aliases (target_id for id), and examples (batch, tag_manage). It adds semantics not present in schema, like 'data accepted as alias for changes' and 'target defaults to task'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create, update, complete, or delete OmniFocus tasks and projects.' It lists all operations and distinguishes itself from sibling tools (omnifocus_analyze, omnifocus_read) which are read-only. The verb 'manage' in the title also reinforces purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each operation, including batch usage, folder creation, and tag management. It includes safety warnings ('Delete is permanent - confirm with user first'), execution order in batches, and data formats. It clearly differentiates from alternatives by stating it is for mutations, while siblings are for reading/analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
System utilities for OmniFocus MCP: get version information, run diagnostics, view performance metrics, or get cache statistics. Use operation="version" for version info, operation="diagnostics" to test OmniFocus connection, operation="metrics" for performance analytics, operation="cache" for cache statistics.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | No | Operation to perform: get version info, run diagnostics, get performance metrics, or get cache statistics | |
| testScript | No | Optional custom script to test for diagnostics (defaults to basic list_tasks) | |
| metricsType | No | Type of metrics to return: summary for overview, detailed for full metrics | |
| cacheAction | No | Cache action: stats to get statistics, clear to invalidate all cached data |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context by specifying the nature of each operation (e.g., 'test OmniFocus connection', 'get cache statistics'), which aligns with the annotations. It does not introduce any contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first lists capabilities, and the second provides explicit usage mappings. Every sentence adds value, and the structure is front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a system utility with no output schema and fully described parameters, the description covers all key operations and their usage. It could explicitly mention that the tool is read-only (though annotations already do), but overall it is complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all parameters having descriptions. The description adds minor value by explaining the operation parameter's mapping in detail, but does not provide additional meaning for other parameters beyond what the schema already offers. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is for 'System utilities for OmniFocus MCP' and enumerates specific operations: version, diagnostics, metrics, cache. This provides a clear verb+resource combination and distinguishes from sibling tools (analyze, read, write) which handle data operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly maps operation values to their actions, e.g., 'Use operation="version" for version info'. This provides clear guidance on when to use each operation. However, it does not explicitly say when to use this tool versus the sibling tools, though the context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v4.1.0omnifocus_analyzeomnifocus_readomnifocus_writesystemEach tool has a clear, distinct purpose: analysis, reading, writing, and system utilities. There is no overlap or ambiguity between them.
All tools follow a consistent 'omnifocus_verb' pattern, making it predictable and easy for agents to understand the action each tool performs.
With only 4 tools for a complex domain like OmniFocus, the count feels low. However, each tool is richly featured, especially read and write, which compensates somewhat.
The tool surface covers most essential operations: CRUD for tasks/projects, folder creation, tag management, analytics, and system diagnostics. Minor gaps exist, such as no explicit perspective management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Secure AI access to OpenOak tasks, notes, and Kanban boards.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kip-d/omnifocus-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
