mcp-omniplan-jtr

Drive OmniPlan 4 on macOS from Claude (or any MCP-compatible LLM agent) using natural language.

Tell an agent "create a milestone called Beta Launch under the Deployment group, link it after the QA-complete task, and assign it to Alice." It does. The Gantt redraws.

20 tools across tasks, dependencies, resources, assignments, and project metadata. MIT-licensed. macOS only.

Lineage: this build is inspired by xiahan4956/omniplan-mcp (MIT) — the original jxa.py bridge is reused under MIT. The rest of the codebase was rebuilt from scratch (~86% of current LOC). It's distributed under a distinct PyPI name (mcp-omniplan-jtr) so as not to take the original author's namespace. See CHANGELOG.md for what changed.

What it does

Related MCP server: OmniFocus MCP Server

Requirements

• macOS (any recent version)

• OmniPlan 4 — installed and running with a document open. See "Supported OmniPlan versions" below for the matrix

• Python 3.11+

• Automation permission granted to your terminal / MCP host app (System Settings → Privacy & Security → Automation → enable OmniPlan)

Supported OmniPlan versions

This MCP is verified against the following builds. "Verified" = full pytest integration suite passes against that build inside a Tart macOS VM with OmniPlan running.

Reporting a version compatibility issue: if you find a build where a tool fails that the matrix says should work, please file an issue with the build number (visible in OmniPlan → About OmniPlan) and the tool name.

Install

Pick whichever you prefer:

# 1. Homebrew tap (Python deps bundled in an isolated venv; only python@3.13 comes from brew)
brew tap johntrandall/tap
brew install mcp-omniplan-jtr

# 2. uv tool (recommended for the MCP ecosystem; installs from PyPI)
uv tool install mcp-omniplan-jtr

# 3. pip (if you don't have uv)
pip install mcp-omniplan-jtr

All three install the mcp-omniplan-jtr command. Register it as an MCP server with whichever client you use:

Claude Code (CLI)

claude mcp add -s user omniplan-local mcp-omniplan-jtr

Then restart Claude Code.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "omniplan-local": {
      "command": "mcp-omniplan-jtr"
    }
  }
}

Then restart Claude Desktop.

First call — Automation permission

The first time the agent calls a tool, macOS may prompt for Automation access. Approve OmniPlan automation for your terminal or the app running the MCP server. If the prompt was missed, grant it manually:

System Settings → Privacy & Security → Automation — enable OmniPlan for your terminal or MCP host.

If denied, every tool returns a clear error: "macOS blocked Automation access to OmniPlan. Grant permission in System Settings > Privacy & Security > Automation."

Tools

All tools accept an optional document_name parameter. If omitted, the frontmost open document is used.

Example prompts

"Show me all incomplete tasks due this week in my project."

"Create a milestone called 'Beta Launch' under the Deployment group, dependent on 'QA-complete', and assign it to Alice at 50%."

"Mark task 42 as complete and set its bar color to green."

"What tasks are assigned the red color?"

"List every resource and how much they're allocated across the project."

Limitations

A few small omniJS edges. Per-version availability is in the supported-versions matrix above; this section names what's currently outside the omniJS surface entirely.

• Resource working hours are not editable through this MCP — actual.rootResource.schedule is opaque on the omniJS surface.

• Project currency (actual.currency) is not writable — writes via omniJS don't persist across calls. Cost values themselves work; just not the currency unit.

• OmniPlan must be running with a document open. The MCP doesn't launch OmniPlan or open documents for you.

For per-release detail and verification status, see CHANGELOG.md.

For the full catalogue (and the mitigations), see dev-docs/omnijs-persistence-gaps.md.

For developers

If you want to extend, hack on, or contribute to this MCP:

• Architecture & internals: dev-docs/README-DEV.md

• Roadmap & feature tiers: dev-docs/ROADMAP.md

• Testing policy: dev-docs/testing-policy.md

• VM provisioning for the pre-release test runner: dev-docs/vm-provisioning.md

Related projects

Sibling OmniPlan tooling in the same workflow:

• oplx-tools — Python toolkit for OmniPlan .oplx documents: generate, lint, parse. Useful when you want to build a Gantt from a database or CI pipeline rather than the GUI.

• oplx-format — Community-maintained file-format specification for .oplx documents (verified against OmniPlan 4.10.2). Reference doc that informed both oplx-tools and the e2e XML cross-checks in this MCP's test suite.

License

MIT. See LICENSE.