codex-omnifocus-mcp

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.

What This Repo Is

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 -> OmniFocus

The GitHub repo's role is distribution: source code, docs, install scripts, tests, and release history.

Install From A Clone

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.sh

To 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.sh

The 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.js

If Codex does not show the new tools immediately, restart Codex or open a new Codex session.

Local Development

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:codex

Create Your Own OmniFocus Agent

This 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.md

Then 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.

Audit Logs

Write tools append JSONL entries to:

~/.codex/codex-omnifocus-mcp/audit/YYYY-MM-DD.jsonl

Override the directory with:

export CODEX_OMNIFOCUS_AUDIT_DIR=/path/to/audit

Audited tools:

• add_omnifocus_task
• add_project
• edit_item
• move_task
• remove_item
• batch_add_items
• batch_remove_items
• create_tag

Verification

npm test
npm run build
npm audit --omit=dev

OmniFocus integration tests should be run manually with OmniFocus open on macOS.

Privacy

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.

Architecture

See docs/architecture.md for the local runtime model and trust boundary.

Distribution

See docs/distribution.md for the public GitHub, local-first release strategy.

Marketing

See docs/marketing.md for launch positioning, channels, content ideas, and the first 30 days of public distribution work.

Notices

See NOTICE.md for upstream attribution.