OmniFocus MCP Server

Сервер Model Context Protocol (MCP), который подключает OmniFocus к Claude и другим MCP-совместимым ИИ-ассистентам.

Обзор

Этот сервер связывает ИИ-ассистентов с вашей базой данных OmniFocus. В ходе естественного разговора ассистент может запрашивать, создавать, редактировать и удалять задачи и проекты — включая массовые операции. Вот что можно с ним делать:

• Преобразовать PDF-файл с учебным планом в полностью специфицированный проект с задачами, тегами, датами откладывания и сроками

• Превратить стенограмму встречи в список действий

• Аудитировать и реорганизовывать теги, проекты и папки в разговоре

• Создавать визуализации ваших задач, проектов и тегов

• Обрабатывать десятки элементов за одну пакетную операцию

Related MCP server: MCP OmniFocus

Быстрый старт

Предварительные требования

• macOS с установленным OmniFocus

• Node.js 20 или новее (для npx)

При первом обращении сервера к OmniFocus macOS попросит разрешить доступ к автоматизации. Предоставьте его один раз — и всё готово.

Claude Desktop

Добавьте сервер в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "omnifocus": {
      "command": "npx",
      "args": ["-y", "omnifocus-mcp"]
    }
  }
}

Затем перезапустите Claude Desktop.

Claude Code

claude mcp add omnifocus -- npx -y omnifocus-mcp

Другие MCP-клиенты работают аналогично: запустите npx -y omnifocus-mcp через stdio.

Примеры диалогов

Точечные запросы:

«Покажи все мои отмеченные флагом задачи, срок которых наступает на этой неделе»

«Какие у меня следующие действия в папке „Работа“?»

«Подсчитай, сколько задач в каждом проекте»

Реорганизация:

«Я хочу, чтобы у каждой задачи был тег уровня энергии. Покажи мне список всех задач, у которых его нет, и свои предложения, какой тег добавить. Я внесу любые изменения, которые сочту нужными. Затем внеси изменения в OmniFocus.»

Захват из любого места:

«Спасибо за подробное объяснение, почему верховенство закона важно. Добавь повторяющуюся задачу в мой проект по активизму, которая напоминает мне звонить моему представителю еженедельно. Включи краткое содержание этого разговора в поле заметок.»

Работа с перспективами:

«Какие перспективы у меня доступны?»

«Покажи, что находится в моей перспективе „Входящие“»

Обработка стенограмм или PDF:

«Я вставляю стенограмму сегодняшней встречи. Проанализируй её и создай задачи в OmniFocus для всех пунктов действий, назначенных мне. Помести их в мой проект „Разработка продукта“.»

Инструменты

Сервер предоставляет 12 инструментов. Необязательные параметры отмечены.

query_omnifocus

Запрос задач, проектов или папок с точечными фильтрами — гораздо быстрее и легче, чем выгрузка всей базы данных. Полную справку см. в QUERY_TOOL_REFERENCE.md, а примеры — в QUERY_TOOL_EXAMPLES.md.

Доступные фильтры:

• Контейнеры: projectName (частичное совпадение без учёта регистра; "inbox" нацеливается на входящие), projectId, folderId (включая подпапки), folderName (частичное совпадение без учёта регистра, включая подпапки)

• Имена: taskName (частичное совпадение без учёта регистра)

• Теги: tags (точное совпадение, с учётом регистра)

• Статус: status — задачи: Next, Available, Blocked, DueSoon, Overdue, Completed, Dropped; проекты: Active, OnHold, Done, Dropped

• Даты, ориентированные в будущее: dueWithin, deferredUntil, plannedWithin (диапазоны), dueOn, deferOn, plannedOn (точный день). Принимают число дней, "today", "tomorrow", "this week", "next week" или дату в формате ISO

• Даты, ориентированные в прошлое: addedWithin, addedOn, completedWithin, completedOn, droppedWithin, droppedOn (фильтры завершённых/отброшенных требуют includeCompleted: true)

• Флаги и прочее: flagged, inbox, hasNote, isRepeating, reviewDue (только для проектов)

dump_database

Получить полное состояние вашей базы данных. Используйте для всестороннего анализа; для точечных запросов предпочитайте query_omnifocus.

• hideCompleted (необязательно): скрыть завершённые/отброшенные задачи (по умолчанию: true)

• hideRecurringDuplicates (необязательно): скрыть дубликаты повторяющихся задач (по умолчанию: true)

add_omnifocus_task

Создать новую задачу.

• name

• projectName (необязательно): проект, в который добавить задачу (по умолчанию — входящие)

• parentTaskId / parentTaskName (необязательно): вложить под существующую задачу

• note, dueDate, deferDate, plannedDate, flagged, estimatedMinutes, tags (все необязательные)

• repeat (необязательно): сделать повторяющейся — см. Повторяющиеся элементы

add_project

Создать новый проект.

• name

• folderName (необязательно): папка, в которую поместить проект

• sequential (необязательно): должны ли задачи выполняться по порядку

• note, dueDate, deferDate, flagged, estimatedMinutes, tags, repeat (все необязательные)

edit_item

Редактировать существующую задачу или проект. Также способ перемещения элементов — задайте newProjectName, чтобы переместить задачу в проект, или ""/"inbox", чтобы отправить её во входящие.

• id или name: какой элемент редактировать (id имеет приоритет)

• itemType: task или project

• Общие: newName, newNote, newDueDate, newDeferDate, newFlagged, newEstimatedMinutes (даты в формате ISO; пустая строка очищает)

• Задачи: newStatus (incomplete, completed, dropped, skipped — skipped только для повторяющихся задач), addTags, removeTags, replaceTags, newProjectName, newPlannedDate

• Проекты: newProjectStatus (active, completed, dropped, onHold), newFolderName, newSequential, markReviewed (устанавливает следующую дату проверки на основе интервала проверки проекта)

• Повторение: newRepeat задаёт новое правило (та же форма, что и repeat при создании); newRepeat: null очищает его

remove_item

Удалить задачу или проект.

• id или name: какой элемент удалить

• itemType: task или project

batch_add_items

Создать несколько задач и проектов одной операцией. Каждый элемент принимает те же поля, что и add_omnifocus_task / add_project, плюс type (task или project) и необязательные помощники иерархии:

• tempId: временный идентификатор, на который могут ссылаться другие элементы того же пакета

• parentTempId: вложить этот элемент под tempId другого элемента пакета

{
  "items": [
    { "type": "project", "name": "My Project", "tempId": "proj1" },
    { "type": "task", "name": "First task", "parentTempId": "proj1" },
    { "type": "task", "name": "Parent task", "parentTempId": "proj1", "tempId": "t1" },
    { "type": "task", "name": "Subtask", "parentTempId": "t1" }
  ]
}

batch_remove_items

Удалить несколько задач или проектов одной операцией. Каждый элемент принимает id или name, плюс itemType.

list_perspectives

Список доступных перспектив, как встроенных, так и пользовательских (пользовательские перспективы — функция OmniFocus Pro).

• includeBuiltIn, includeCustom (необязательно, по умолчанию: true)

get_perspective_view

Получить элементы, видимые в указанной перспективе.

• perspectiveName: например, Inbox, Flagged или имя пользовательской перспективы

• limit (необязательно, по умолчанию: 100), includeMetadata (необязательно), fields (необязательно)

list_tags

Список всех тегов с их иерархией, статусом активности и количеством задач.

• includeDropped (необязательно, по умолчанию: false)

create_tag

Создать тег, при необходимости вложенный под существующий родительский.

• name

• parentTagName / parentTagID (необязательно; ID имеет приоритет)

Повторяющиеся элементы

add_omnifocus_task, add_project и каждый элемент в batch_add_items принимают объект repeat; edit_item принимает newRepeat. Вы описываете расписание, а сервер компилирует правило повторения ICS, так что вам никогда не придётся писать RRULE вручную.

{ "name": "Weekly review", "repeat": { "method": "start-after-completion", "unit": "week" } }
{ "name": "Strength work", "repeat": { "method": "fixed", "unit": "week", "weekdays": ["TU","TH"] } }

Выбирайте method осознанно — это поле чаще всего задают неправильно вручную. При fixed повторения появляются по расписанию независимо от того, было ли выполнено предыдущее, так что пропущенная неделя оставляет накопленный долг. При start-after-completion следующее повторение планируется от момента фактического выполнения, так что привычка просто возобновляется.

Прочитайте правило обратно с помощью query_omnifocus, используя поля repetitionRule (строка ICS) и repetitionMethod, или отфильтруйте по isRepeating.

В настоящее время не поддерживаются: позиционные месячные правила («третий вторник»), конкретные дни месяца и условия окончания (COUNT/UNTIL). Задавайте их непосредственно в OmniFocus.

Ресурсы

Ресурсы позволяют MCP-клиентам прикреплять данные OmniFocus к разговору в качестве контекста, без вызовов инструментов. В Claude Code введите @, чтобы просмотреть их; Claude Desktop и другие клиенты, поддерживающие ресурсы, могут прикреплять их напрямую. Все ресурсы возвращают JSON.

Два шаблонных ресурса поддерживают перечисление всех доступных значений и автодополнение параметра {name}.

Инструкции сервера и журналирование

Инструкции: во время рукопожатия MCP сервер отправляет клиенту руководство по использованию — советы по выбору инструментов (предпочитайте query_omnifocus вместо dump_database), подсказки по фильтрам и каталог ресурсов. Настройка не требуется.

Журналирование: сервер отправляет структурированные журналы через протокол журналирования MCP. Клиенты могут регулировать подробность с помощью logging/setLevel (debug, info, warning, error, ...). Время выполнения скриптов и ошибки регистрируются автоматически.

Как это работает

Сервер общается с OmniFocus через osascript, используя JXA (JavaScript for Automation) и встроенную автоматизацию OmniFocus (OmniJS), где это уместно. Он построен на официальном MCP TypeScript SDK и общается с клиентами через stdio.

Общий фоновый процесс

Запуск omnifocus-mcp запускает небольшой shim, который подключается к общему фоновому процессу, запуская его, если он ещё не работает. Каждый клиент на машине получает собственную независимую MCP-сессию, но все они работают внутри этого единственного процесса.

Это важно, когда несколько агентов одновременно используют OmniFocus. OmniFocus — это однопоточное приложение, управляемое через AppleEvents, и сервер ограничивает количество одновременных вызовов osascript. Когда каждый клиент запускал собственный сервер, этот лимит был на процесс — десять клиентов означали десять независимых бюджетов, направленных на одно приложение, что приводило к тайм-аутам AppleEvent. Общий процесс делает лимит глобальным.

Фоновый процесс прослушивает Unix-сокет в каталоге с правами 0700 (по умолчанию ~/.omnifocus-mcp/daemon-<version>.sock), поэтому доступ контролируется файловой системой — ни сетевого порта, ни токена. Он завершается сам, когда в течение idle-окна не остаётся подключённых клиентов, и ведёт журнал в daemon.log рядом с сокетом.

Имя сокета содержит версию пакета, так что обновление никогда не оставит вас на связи с фоновым процессом предыдущей версии. Сразу после обновления вы можете ненадолго увидеть два фоновых процесса: старый продолжает обслуживать уже подключённых клиентов и завершается, когда последний из них отключается. Клиенты, всё ещё подключённые к старому процессу, узнают об этом встроенным способом — пока работает более новый процесс, каждый результат инструмента содержит однострочное уведомление об обновлении, так что никому не нужно помнить о переподключении.

Конфигурация клиентов не меняется. Если фоновый процесс не может быть запущен — необычная песочница, домашний каталог только для чтения — shim переключается на запуск автономного сервера в процессе, как в более ранних версиях.

Переменные окружения

Дорожная карта

• Поддержка MCP prompt

• Управление уведомлениями для проектов и задач

• См. GitHub issues для запросов функций и известных проблем

Вклад

Вклад приветствуется! Пожалуйста, не стесняйтесь отправлять pull request. CI запускает проверку типов, модульные тесты и сборку для каждого PR.

npm install
npm test            # unit tests
npm run build       # compile to dist/
npm run test:integration  # requires OmniFocus; creates and removes TEST:-prefixed items

Лицензия

MIT