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

You say	The agent calls	OmniPlan reflects
"Show me incomplete tasks due this week"	query_tasks(due_before=…, completed=false)	filters the outline
"Create a 4-hour task 'Refactor login' under Auth"	create_task(parent_id, effort_seconds=14400)	new row in the Gantt
"Link 'Refactor login' before 'Run E2E'"	add_dependency(predecessor_id, successor_id, kind="FS")	dependency arrow drawn
"Assign Alice at 50%"	assign_resource(task_id, resource_id, units=0.5)	assignment chip on the bar
"Mark Beta Launch as a milestone, color green"	update_task(type="milestone", color="green")	diamond marker, green
"Save the document"	save_document()	written to disk

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.

OmniPlan version	Build	All tools?	Verified	Notes
4.10.3 test	v232.5.9 (e7066d2251)	✅ All 22 tools	2026-05-07	Test build from https://omnistaging.omnigroup.com/omniplan/. Adds task.move / resource.move — Ken Case (Omni Group) shipped these in May 2026 in response to OG ticket #3107771
4.10.2	232.5.0	✅ Except move_task / move_resource	2026-05-01	Public release. The two move tools raise a clear "requires 4.10.3+" error; everything else works including all reads, writes, dependencies, resource assignments, and cost_per_use
4.10.0–4.10.1	(older 4.10.x patch builds)	Likely yes for non-move tools	Inferred (untested)	Should work — same omniJS surface as 4.10.2 for the tools we use, but not empirically verified
4.9.x and older	—	Unknown	Untested	Not part of the supported matrix

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

Tool	What it does
list_documents	List all currently open OmniPlan documents
query_tasks	Search and filter tasks by keyword, type, completion, color, or date range
find_task	Look up tasks by title; substring by default, exact opt-in
get_task	Get full details of a task by ID
create_task	Create a new task under a parent task or project root
create_tasks	Bulk-create many tasks in a single round-trip; supports intra-batch parent references
update_task	Update title, note, dates, completion, color, effort, three-point estimates, constraint dates
move_task	Reparent a task while preserving its uniqueID (so dependencies and assignments survive). Requires OmniPlan 4.10.3+
delete_task	Delete a task by ID
add_dependency	Link two tasks (FS / SS / FF / SF, optional lead time)
remove_dependency	Remove the dependency between two tasks
list_dependencies	List dependencies in the document (or filtered to one task)
save_document	Save the front document to disk
get_project_info	Project metadata: name, path, dates, scenarios
update_project	Update project-level fields (currently start date)
list_resources	List all resources
create_resource	Create a resource (staff / equipment / material / group)
move_resource	Reparent a resource (across the resource group hierarchy) while preserving its uniqueID. Requires OmniPlan 4.10.3+
delete_resource	Delete a resource by ID
assign_resource	Assign a resource to a task with optional units fraction
unassign_resource	Remove a resource assignment from a task
list_assignments	List a task's resource assignments

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.