Click on "Deploy 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., "@codex-omnifocus-mcp Add a task to review design doc due Friday"
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.
Local Codex-focused MCP server for OmniFocus on macOS.
This project starts from omnifocus-mcp-enhanced and adds Codex-oriented server instructions, MCP resources, compact query tools, tag tools, clean shutdown, logging, and write audit logging.
This repository is the source code for a local MCP server. It is not a hosted web service and it does not run a central cloud server.
Each user installs this repo on their own Mac. Codex starts the MCP server locally with Node.js, talks to it over stdio, and the server reads or updates the user's local OmniFocus database through AppleScript/JXA.
In short:
Codex -> local MCP stdio -> node dist/server.js -> AppleScript/JXA -> OmniFocusThe GitHub repo's role is distribution: source code, docs, install scripts, tests, and release history.
Related MCP server: OmniFocus MCP Server
git clone https://github.com/phd-peter/codex-omnifocus-mcp.git ~/.local/share/codex-omnifocus-mcp
cd ~/.local/share/codex-omnifocus-mcp
scripts/install-codex.shTo clone from a script-driven install after downloading this script separately:
CODEX_OMNIFOCUS_REPO_URL=https://github.com/phd-peter/codex-omnifocus-mcp.git scripts/install-codex.shThe installer runs npm ci, builds the TypeScript output, and registers the MCP server with Codex:
codex mcp add codex-omnifocus -- node /path/to/codex-omnifocus-mcp/dist/server.jsIf Codex does not show the new tools immediately, restart Codex or open a new Codex session.
npm install
npm run build
codex mcp add codex-omnifocus -- node "$PWD/dist/server.js"The server is intended for local use. package.json remains marked private as an npm publishing guard; the GitHub repository can still be public.
Useful commands:
npm test
npm run build
npm run preflight
npm run register:codexThis repo provides the shared MCP server and the default Codex tool-use guidance in skills/codex-omnifocus/SKILL.md. Your personal agent behavior should live in a separate AGENTS.md so each user can define their own OmniFocus system without changing the server.
Start from the template:
cp AGENTS.example.md AGENTS.mdThen edit AGENTS.md for your own workflow:
default capture destination
tags and custom perspectives
due/defer date habits
daily planning and weekly review style
when the agent may write directly and when it should ask first
Personal AGENTS.md files are ignored by default because they can include sensitive project names, routines, or decision rules.
Write tools append JSONL entries to:
~/.codex/codex-omnifocus-mcp/audit/YYYY-MM-DD.jsonlOverride the directory with:
export CODEX_OMNIFOCUS_AUDIT_DIR=/path/to/auditAudited tools:
add_omnifocus_task
add_project
edit_item
move_task
remove_item
batch_add_items
batch_remove_items
create_tag
npm test
npm run build
npm audit --omit=devOmniFocus integration tests should be run manually with OmniFocus open on macOS.
See PRIVACY.md. Audit logs and OmniFocus exports can contain private task, project, tag, date, and note data. Do not commit backups/, exports/, .env*, audit/, or *.jsonl.
See docs/architecture.md for the local runtime model and trust boundary.
See docs/distribution.md for the public GitHub, local-first release strategy.
See docs/marketing.md for launch positioning, channels, content ideas, and the first 30 days of public distribution work.
See NOTICE.md for upstream attribution.
Create a NEW task in OmniFocus. Search first when a matching task may already exist; move/edit existing tasks instead of duplicating them.
Inputs: name (required), note, dueDate, deferDate, +7 more.
Add a new project to OmniFocus
Inputs: name (required), note, dueDate, deferDate, +6 more.
Add multiple tasks or projects to OmniFocus in a single operation
Inputs: items (required).
Remove multiple tasks or projects from OmniFocus in a single operation. Prefer IDs for destructive batch operations.
Inputs: items (required).
Create a new tag in OmniFocus, optionally nested under an existing parent tag.
Inputs: name (required), parentTagName, parentTagID.
Gets the current state of your OmniFocus database. Prefer query_omnifocus or filter_tasks for targeted lookups.
Inputs: hideCompleted, hideRecurringDuplicates.
Edit an existing task or project in OmniFocus. Also supports moving tasks via project, parent task, or inbox move fields.
Inputs: itemType (required), id, name, newName, +18 more.
Advanced task filtering with unlimited perspective combinations - status, dates, projects, tags, search, and more
Inputs: taskStatus, perspective, projectFilter, tagFilter, +32 more.
Get tasks from a specific OmniFocus custom perspective by name. Use when the user refers to a custom view, not a tag.
Inputs: perspectiveName (required), hideCompleted, limit, displayMode, +2 more.
Get flagged tasks from OmniFocus with optional project filtering
Inputs: hideCompleted, projectFilter.
Get tasks from OmniFocus forecast perspective (due/deferred tasks in date range)
Inputs: days, hideCompleted, includeDeferredOnly.
Get tasks from OmniFocus inbox perspective
Inputs: hideCompleted.
Get information about a specific task by ID or name, including attachment metadata when available.
Inputs: taskId, taskName.
Get tasks filtered by OmniFocus tags. Use this for tag names, not custom perspective names.
Inputs: tagName (required), hideCompleted, exactMatch.
Get tasks completed today - view today's accomplishments
Inputs: limit.
List all custom perspectives defined in OmniFocus
Inputs: format.
List all tags in OmniFocus with their hierarchy. Useful before creating or editing tagged tasks.
Inputs: includeDropped.
Move an existing task to a project, parent task, or inbox. Prefer task ID and destination IDs when available.
Inputs: id, name, targetProjectId, targetProjectName, +3 more.
Efficiently query OmniFocus database with filters, fields, sorting, limits, and summaries. Prefer this over dump_database for targeted lookups.
Inputs: entity (required), filters, fields, limit, +4 more.
Read a task attachment reported by get_task_by_id. Images are returned as MCP image content when possible.
Inputs: taskId, taskName, attachmentId, attachmentName.
Remove a task or project from OmniFocus. Prefer ID over name for destructive operations.
Inputs: itemType (required), id, name.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 21 tools
Most tools have distinct purposes, with clear descriptions that guide selection (e.g., get_custom_perspective_tasks vs get_tasks_by_tag). However, the large number of retrieval tools (filter_tasks, query_omnifocus, dump_database, multiple get_*) may cause occasional confusion despite differentiating texts.
Predominantly verb_noun snake_case pattern is used (e.g., add_project, filter_tasks, list_tags). Minor inconsistencies exist: 'add_omnifocus_task' vs 'add_project' (one includes product name), 'create_tag' vs 'add_project' (different verbs), and 'edit_item'/'move_task' are slightly vague but acceptable.
21 tools is well-scoped for an OmniFocus integration, covering creation, retrieval, modification, and deletion across tasks, projects, tags, and perspectives. Each tool serves a clear purpose without feeling excessive.
Tool surface covers most core workflows: CRUD for tasks/projects, batch operations, diverse retrieval, and attachment reading. However, tag management is incomplete – only create_tag and list_tags exist, lacking update or delete operations, which is a notable gap.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Lets Claude, ChatGPT, and Muse read and update your beckett tasks, notes, calendar, and lists.
