pymnifocus
This MCP server lets AI assistants read, query, and modify an OmniFocus database (tasks, projects, folders, tags, perspectives) on macOS.
Query the database: use
query_omnifocusto fetch tasks, projects, or folders with filters, field selection, sorting, limits, summaries, and optional inclusion of completed items.Full database dump: use
dump_databaseto retrieve the complete current state for comprehensive analysis.Add items: use
add_omnifocus_taskandadd_projectto create tasks or projects with notes, tags, flags, due/defer/planned dates, project/folder placement, hierarchy, sequential flag, and time estimates.Batch add: use
batch_add_itemsto add up to 100 tasks/projects in one call.Edit items: use
edit_itemto rename or update notes, flagged state, and due/defer/planned dates on a task or project.Remove items: use
remove_itemto delete a task or project by ID or name.Batch remove: use
batch_remove_itemsto delete up to 100 items at once.Inspect perspectives: use
list_perspectivesandget_perspective_viewto discover perspectives and view their contents (with limits and optional metadata).Inspect tags: use
list_tagsto see all tags with their hierarchy, optionally including dropped tags.
Allows Gemini AI assistants (via Google AI Studio) to interact with OmniFocus for querying, adding, editing, and removing tasks and projects.
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., "@pymnifocus Show my overdue tasks"
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.
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 syncCLI 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 --jsonRun 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 pymnifocusRun 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-httpThen 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-httpThis 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-appNote:
host.docker.internalresolves to the host machine on Docker Desktop for Mac and Podman Machine. On Linux with native Docker, add--add-host=host.docker.internal:host-gatewayto thedocker runcommand.
Available MCP Tools
Tool | Description |
| Query tasks, projects, or folders with filters |
| Get full OmniFocus database state |
| Add a new task |
| Add a new project |
| Remove a task or project |
| Edit a task or project |
| Add multiple items at once (max 100) |
| Remove multiple items at once (max 100) |
| List available perspectives |
| Get items from a perspective |
| List all tags with hierarchy |
MCP Resources
URI | Description |
| Current inbox items |
| Today's agenda (due, planned, overdue) |
| All flagged items |
| Database statistics |
| Tasks in a project |
| 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 tagsAppleScript 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
--hostto override
License
MIT
Credits
Inspired by themotionmachine/OmniFocus-MCP. OmniJS scripts are adapted from that project.
Available Tools
11 toolsadd_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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Headless task management for bots, apps and AI agents. Remote MCP server, OAuth or access token.
MCP server for OnceAsk, the AI-native current-address layer for people and agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceA Model Context Protocol (MCP) server that integrates with OmniFocus to enable Claude (or other MCP-compatible AI assistants) to interact with your tasks and projects.7376 npm253MIT
- AlicenseAqualityDmaintenanceAn MCP server that provides full read/write access to OmniFocus, enabling AI assistants to manage tasks, projects, folders, tags, and perspectives via 51 tools, resources, and prompts.5134 npm22MIT
- FlicenseNot gradedqualityBmaintenanceA production-grade MCP server that exposes OmniFocus as structured task infrastructure for AI agents, enabling read, write, and filter operations on tasks and projects via natural language.11-
- AlicenseNot gradedqualityDmaintenanceMCP server that gives AI assistants full control over OmniFocus on macOS, including tasks, projects, tags, folders, perspectives, forecast, notifications, and review workflows.44MIT