Skip to main content
Glama
mdoel

OmniFocus MCP Server

by mdoel
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

OmniFocus MCP Server

A Model Context Protocol (MCP) server for integrating OmniFocus with Claude Desktop. This server provides Claude with access to your OmniFocus tasks and projects, enabling AI-powered task management and weekly reviews.

Features

  • 🎯 OmniFocus Integration - Access tasks and projects from OmniFocus

  • 🔧 Active Task Filtering - Get only uncompleted tasks, excluding templates and system items

  • 🚀 TypeScript + MCP SDK - Type-safe and maintainable

  • 🔒 Secure Automation - Uses official Omni Automation JavaScript API

  • 📱 Claude Desktop Ready - Works seamlessly with Claude Desktop

Related MCP server: Todoist MCP Server

Current Tools

omnifocus:get_all_tasks

Retrieve all tasks from OmniFocus with filtering options:

  • includeCompleted (boolean) - Include completed tasks (default: false)

  • limit (number) - Maximum number of tasks to return (default: 100)

omnifocus:get_active_tasks

Retrieve only active (uncompleted) tasks, automatically filtering out:

  • Tasks from "Templates" folders

  • Tasks containing template placeholders («, »)

  • Tasks with synced preferences markers (⚙️)

omnifocus:get_projects

Retrieve all active projects from OmniFocus.

Prerequisites

  • macOS with OmniFocus installed

  • Node.js 23.10.0 or higher

  • Claude Desktop application

  • Automation permissions for OmniFocus

Installation

  1. Clone the repository:

    git clone https://github.com/mdoel/omnifocus-mcp
cd omnifocus-mcp

  2. Install dependencies:

    npm install

  3. Build the project:

    npm run build

  4. Configure Claude Desktop:

    Add this to your Claude Desktop MCP configuration:

    {
  "mcpServers": {
    "omnifocus": {
      "command": "/path/to/omnifocus/run-server.sh",
      "args": []
    }
  }
}

    Important: Replace /path/to/omnifocus/ with the actual path to your project directory.

  5. Grant automation permissions:

    The first time you run the server, macOS will prompt you to grant automation permissions for OmniFocus. Click "Allow" when prompted.

    Note: If you encounter permission issues, you may need to temporarily uncomment the osascript lines in run-server.sh to trigger the permission dialog. After granting permissions, comment those lines out again to avoid the dialog on every startup.

  6. Restart Claude Desktop to load the new MCP server.

Usage

Once configured, you can ask Claude to:

  • "Get all my active tasks from OmniFocus"

  • "Show me my projects"

  • "What tasks do I have for today?"

  • "Help me with my weekly review"

Architecture

Core Components

  • OmniFocusClient - Handles communication with OmniFocus via Omni Automation

  • OmniFocusJXA - Utility for building and executing JXA scripts

  • OmniFocusMCPServer - Main MCP server implementation

Directory Structure

src/
├── index.ts              # Main entry point
├── server.ts             # MCP server implementation
├── omnifocus/
│   ├── client.ts         # OmniFocus automation client
│   └── omnifocus-jxa.ts  # JXA script utilities
└── types/
    └── omnifocus.ts      # TypeScript definitions

Development

Building

# Build the project
npm run build

# Watch mode for development
npm run dev

Testing

You can test the server locally:

# Test with command line arguments
node dist/index.js all        # Get all tasks
node dist/index.js active     # Get active tasks only
node dist/index.js projects   # Get projects only

Testing OmniFocus Automation

Test OmniFocus automation directly:

# Test basic connection
osascript -l JavaScript -e "Application('OmniFocus').running()"

# Test task retrieval
osascript -l JavaScript -e "
const app = Application('OmniFocus');
const doc = app.defaultDocument;
const tasks = doc.flattenedTasks();
console.log('Found ' + tasks.length + ' tasks');
"

Troubleshooting

Server Connection Issues

If Claude Desktop can't connect to the server:

  1. Check the script path in your Claude Desktop configuration

  2. Verify permissions - ensure the run-server.sh script is executable:

    chmod +x run-server.sh

  3. Check Node.js installation - ensure Node.js 23.10.0+ is installed

  4. Review logs - check Claude Desktop's MCP server logs for error messages

Permission Issues

If you get automation permission errors:

  1. Open System Preferences > Security & Privacy > Privacy

  2. Select Automation from the left sidebar

  3. Find your terminal/shell and check OmniFocus

  4. Restart your terminal and try again

OmniFocus Not Found

  • Ensure OmniFocus is installed and running

  • Verify the app name is "OmniFocus" (not "OmniFocus 3" or something similar)

  • Check that OmniFocus is not in the trash or disabled

Performance Issues

If the server is slow or times out:

  • The server may take time to process large OmniFocus databases

  • Consider using the limit parameter to reduce the number of tasks returned

  • Ensure OmniFocus is not performing other operations

Contributing

This project is designed to be extensible. To add new functionality:

  1. Add new tools in the src/omnifocus/ directory

  2. Update the server to register new tools

  3. Test thoroughly with your OmniFocus data

  4. Submit a pull request with clear documentation

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

  • Check the troubleshooting section above

  • Review the Claude Desktop MCP documentation

  • Open an issue in this repository

Available Tools

4 tools
get_active_projectsA

Call this tool to get a list of all active (not completed or dropped) projects from OmniFocus. Use it when the user asks for their 'active projects' or 'current projects'.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It describes the tool's behavior as retrieving a list of active projects, which is adequate but lacks details like response format, pagination, or error handling. It doesn't contradict any annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by usage guidance in the second. Both sentences earn their place with no wasted words, making it highly efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 0 parameters, no annotations, and no output schema, the description is complete enough by clearly stating what it does and when to use it. It could slightly improve by hinting at the return format, but it's largely sufficient given the low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately adds no parameter details, maintaining focus on the tool's purpose and usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific verb ('get a list') and resource ('all active projects from OmniFocus'), explicitly distinguishing it from siblings by specifying 'active (not completed or dropped)' projects rather than all projects or tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit guidance on when to use this tool ('when the user asks for their "active projects" or "current projects"'), with clear context that distinguishes it from sibling tools like 'get_all_projects' or 'get_active_tasks'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_active_tasksA

Call this tool to get a list of all active (uncompleted) tasks from the user's OmniFocus. Use it when the user asks for their 'active tasks', 'current tasks', or 'open tasks'.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves a list of active tasks, implying a read-only operation, but does not disclose other behavioral traits such as authentication requirements, rate limits, error conditions, or the format of the returned list. For a tool with zero annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with two sentences: the first states the purpose, and the second provides usage guidelines. Every sentence adds value, and there is no wasted text, making it front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is reasonably complete for its purpose. However, it lacks details on behavioral aspects like authentication or output format, which could be important for an AI agent to use it correctly, especially without annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% description coverage, so no parameter documentation is needed. The description does not add parameter semantics, which is appropriate here, but it could have mentioned if any implicit parameters (e.g., user context) are involved. Baseline is 4 for zero parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'get a list of all active (uncompleted) tasks from the user's OmniFocus.' It specifies the verb ('get'), resource ('active tasks'), and scope ('from the user's OmniFocus'), but does not explicitly differentiate it from sibling tools like 'get_all_tasks' beyond the 'active' qualifier.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: 'Use it when the user asks for their 'active tasks', 'current tasks', or 'open tasks'.' This gives explicit guidance on when to invoke the tool, but does not mention when not to use it or name alternatives among the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_all_projectsA

Call this tool to get a list of all projects from OmniFocus, including completed and dropped ones. Use it when the user explicitly asks for 'all projects'.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates this is a read operation ('get a list'), but doesn't mention potential limitations like rate limits, authentication requirements, or response format details. The description adds basic context about what data is included but lacks richer behavioral information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two focused sentences with zero wasted words. The first sentence establishes purpose and scope, the second provides clear usage guidance. Every element serves a specific function, making it efficiently structured and appropriately sized for its complexity level.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read operation with zero parameters and no output schema, the description provides adequate context: purpose, scope, and usage guidance. However, without annotations or output schema, it could benefit from mentioning what the return format looks like (e.g., list structure, fields included) to be fully complete for agent consumption.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and schema description coverage is 100% (though empty). The description appropriately doesn't discuss parameters since none exist, which is correct for a parameterless tool. No additional parameter semantics are needed or provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('get a list of all projects') and resource ('from OmniFocus'), with explicit scope differentiation ('including completed and dropped ones'). It directly distinguishes this tool from its sibling 'get_active_projects' by specifying it returns all projects rather than just active ones.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Use it when the user explicitly asks for 'all projects''. This creates a clear boundary for when to select this tool versus its siblings (like 'get_active_projects'), effectively telling the agent when this specific tool is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_all_tasksA

Call this tool to get a list of all tasks from OmniFocus, including completed ones. Use it when the user explicitly asks for 'all tasks' or 'completed tasks'.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves a list of all tasks, implying a read-only operation, but lacks details on potential limitations like rate limits, authentication needs, or how the data is structured in the response. It adds basic context but misses richer behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and concise, consisting of two sentences that directly address purpose and usage without any wasted words. Every sentence adds clear value, making it efficient and well-structured for quick comprehension by an AI agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is largely complete. It covers the core purpose and usage guidelines effectively. However, it could be more complete by briefly mentioning the response format or any implicit constraints, though this is a minor gap for such a straightforward tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description does not mention any parameters, which is appropriate. A baseline of 4 is applied as it correctly omits unnecessary parameter details, though it could slightly enhance value by noting the lack of filters (e.g., no date ranges).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('get') and resource ('list of all tasks from OmniFocus'), including the scope ('including completed ones'). It distinguishes this tool from siblings like 'get_active_tasks' by explicitly mentioning completed tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool: 'when the user explicitly asks for 'all tasks' or 'completed tasks'.' This directly addresses usage scenarios and implicitly suggests alternatives (e.g., 'get_active_tasks' for non-completed tasks), making it highly actionable for an AI agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updates
    • First observedget_active_projects
    • First observedget_active_tasks
    • First observedget_all_projects
    • First observedget_all_tasks
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: get_active_projects vs. get_all_projects differentiate by completion status, and similarly for tasks. The descriptions explicitly clarify when to use each tool, eliminating any potential for misselection.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with 'get_' prefix and descriptive suffixes (e.g., active_projects, all_tasks). There are no deviations in naming style, making the set predictable and easy to understand.

Tool Count4/5

Four tools are reasonable for a basic OmniFocus integration, covering core read operations for projects and tasks. However, the scope feels slightly thin as it lacks update, create, or delete capabilities, which might be expected for a task management system.

Completeness2/5

The tool set is severely incomplete for OmniFocus functionality. It only provides read operations for projects and tasks, with no ability to create, update, delete, or manage other entities like contexts, tags, or due dates. This will cause significant agent failures in handling typical task management workflows.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mdoel/omnifocus-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server