Skip to main content
Glama

pymnifocus

A Python toolkit for OmniFocus on macOS: an MCP server for AI assistant integration (Cursor, Claude, Gemini) and a standalone CLI query tool.

Inspired by themotionmachine/OmniFocus-MCP, rebuilt in Python with security hardening, a CLI, and PyPI packaging.

Prerequisites

  • macOS with OmniFocus installed and running

  • Python 3.11+

  • uv (recommended) or pip

Related MCP server: OmniFocus MCP Server

Installation

# From PyPI
pip install pymnifocus

# Or with uv
uv pip install pymnifocus

# For development
git clone https://github.com/vdanen/pymnifocus.git
cd pymnifocus
uv sync

CLI Query Tool

Query OmniFocus directly from your terminal with pymnifocus-query:

# Shorthand flags
pymnifocus-query --overdue
pymnifocus-query --flagged --sort dueDate
pymnifocus-query --inbox
pymnifocus-query --due-within 7 --limit 10
pymnifocus-query --project "Weekly Review"
pymnifocus-query --tag work --tag urgent
pymnifocus-query --available --summary
pymnifocus-query --today

# JSON input (same format as MCP query_omnifocus tool)
pymnifocus-query '{"entity": "tasks", "filters": {"status": ["Overdue", "DueSoon"]}, "sortBy": "dueDate"}'

# Pipe from stdin
echo '{"entity": "projects", "filters": {"status": ["Active"]}}' | pymnifocus-query

# Other tools
pymnifocus-query --tags
pymnifocus-query --perspectives
pymnifocus-query --dump

# Raw JSON output (for scripting)
pymnifocus-query --overdue --json

Run pymnifocus-query --help for full usage.

MCP Server

The MCP server enables AI assistants to interact with OmniFocus through natural language.

Running the Server

# Stdio transport (default, for Cursor/Claude/Gemini)
pymnifocus-server

# Streamable HTTP transport (for web clients or container access)
pymnifocus-server --transport streamable-http
pymnifocus-server --transport streamable-http --port 9000

# Or via module
python -m pymnifocus

Run pymnifocus-server --help for all options.

Cursor Integration

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "omnifocus": {
      "command": "pymnifocus-server"
    }
  }
}

Or if using uv from a local clone:

{
  "mcpServers": {
    "omnifocus": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/pymnifocus",
        "python",
        "-m",
        "pymnifocus.server"
      ]
    }
  }
}

Restart Cursor or reload MCP servers (Cmd+Shift+P -> "MCP: Restart Servers").

Claude Code Integration

Same as above, just edit ~/.claude.json.

Claude Desktop Integration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "omnifocus": {
      "command": "pymnifocus-server"
    }
  }
}

Restart Claude Desktop.

Google AI Studio / Gemini

For MCP-compatible Gemini clients, the server uses stdio transport by default:

  • Command: pymnifocus-server

For Streamable HTTP (web-based clients):

pymnifocus-server --transport streamable-http

Then connect to http://localhost:8000/mcp.

Container Access

Since OmniFocus is a macOS application, the MCP server must run on the macOS host. Containers can reach it over HTTP using host.docker.internal.

1. Start the server on the host:

pymnifocus-server --transport streamable-http

This binds to 127.0.0.1:8000 by default. OmniFocus must be running.

2. Configure the MCP client inside the container:

{
  "mcpServers": {
    "omnifocus": {
      "url": "http://host.docker.internal:8000/mcp"
    }
  }
}

3. Sample Containerfile:

FROM python:3.13-slim

RUN pip install --no-cache-dir mcp-client-cli

# Configure MCP to reach the host's pymnifocus server
RUN mkdir -p /root/.config
COPY <<'EOF' /root/.config/mcp.json
{
  "mcpServers": {
    "omnifocus": {
      "url": "http://host.docker.internal:8000/mcp"
    }
  }
}
EOF

CMD ["bash"]

Build and run (Docker or Podman):

docker build -t my-mcp-app .
docker run --rm -it my-mcp-app

Note: host.docker.internal resolves to the host machine on Docker Desktop for Mac and Podman Machine. On Linux with native Docker, add --add-host=host.docker.internal:host-gateway to the docker run command.

Available MCP Tools

Tool

Description

query_omnifocus

Query tasks, projects, or folders with filters

dump_database

Get full OmniFocus database state

add_omnifocus_task

Add a new task

add_project

Add a new project

remove_item

Remove a task or project

edit_item

Edit a task or project

batch_add_items

Add multiple items at once (max 100)

batch_remove_items

Remove multiple items at once (max 100)

list_perspectives

List available perspectives

get_perspective_view

Get items from a perspective

list_tags

List all tags with hierarchy

MCP Resources

URI

Description

omnifocus://inbox

Current inbox items

omnifocus://today

Today's agenda (due, planned, overdue)

omnifocus://flagged

All flagged items

omnifocus://stats

Database statistics

omnifocus://project/{name}

Tasks in a project

omnifocus://perspective/{name}

Items in a perspective

Example Prompts

  • "Show me all flagged tasks due this week"

  • "Add a task 'Review quarterly report' to my Work project, due Friday"

  • "What's in my inbox?"

  • "List all my projects"

  • "Create a project called 'Website Redesign' with 3 tasks"

How It Works

The server communicates with OmniFocus using:

  • OmniJS scripts executed via JXA (osascript -l JavaScript) for queries, dumps, perspectives, and tags

  • AppleScript for add/edit/remove operations

OmniFocus must be running for either the MCP server or the CLI tool to function.

Security

  • All user input is validated and escaped before embedding in generated scripts

  • Entity names, sort fields, and field names are whitelisted

  • Numeric parameters are validated as integers

  • AppleScript strings are sanitized against injection (quotes, backslashes, newlines)

  • Script paths are constrained to prevent directory traversal

  • Batch operations are capped at 100 items

  • Query results are capped at 5000 items

  • Stdio transport: all communication is local (no network traffic)

  • HTTP transport: binds to localhost by default; use --host to override

License

MIT

Credits

Inspired by themotionmachine/OmniFocus-MCP. OmniJS scripts are adapted from that project.

Available Tools

11 tools
add_omnifocus_taskC

Add a new task to OmniFocus.

Inputs: name (required), note, tags, flagged, +7 more. Returns: result

add_projectC

Add a new project to OmniFocus.

Inputs: name (required), note, tags, flagged, +5 more. Returns: result

batch_add_itemsB

Add multiple tasks or projects in a single operation (max 100).

Inputs: items (required). Returns: result

batch_remove_itemsB

Remove multiple tasks or projects in a single operation (max 100).

Inputs: items (required). Returns: result

dump_databaseC

Get the complete current state of your OmniFocus database. Best for comprehensive analysis.

Inputs: hide_completed, hide_recurring_duplicates. Returns: result

edit_itemC

Edit a task or project in OmniFocus.

Inputs: item_type (required), id, name, new_name, +5 more. Returns: result

get_perspective_viewC

Get items visible in a specific OmniFocus perspective.

Inputs: perspective_name (required), limit, include_metadata. Returns: result

list_perspectivesB

List all available perspectives in OmniFocus.

Inputs: include_custom, include_built_in. Returns: result

list_tagsB

List all tags in OmniFocus with their hierarchy.

Inputs: include_dropped. Returns: result

query_omnifocusA

Efficiently query OmniFocus database with filters. Get specific tasks, projects, or folders.

Task filters include completedAfter and completedBefore (ISO date or datetime, local timezone) to restrict by completionDate; set include_completed true or completed tasks are excluded first.

Inputs: entity (required), limit, fields, filters, +4 more. Returns: result

remove_itemA

Remove a task or project from OmniFocus. Provide either id or name.

Inputs: item_type (required), id, name. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct operation: adding, editing, removing, querying, listing tags/perspectives, etc. The batch variants are clearly separated from single-item operations, and the query/dump tools serve different analytical needs.

    Naming Consistency4/5

    Most tools follow a clear verb_noun pattern such as add_project, remove_item, list_tags. Minor deviations like dump_database and query_omnifocus use different prefixes, but the overall style remains readable and predictable.

    Tool Count5/5

    11 tools is well-scoped for an OmniFocus MCP server, covering CRUD operations, batch operations, querying, and viewing perspectives/tags. The count feels balanced and not excessive for the domain.

    Completeness4/5

    Core lifecycle operations are covered (add, edit, remove, batch, query), along with supporting features like tags and perspectives. Minor gaps exist, such as no explicit 'complete task' tool, but these can be handled via edit_item or query filters.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers