OmniFocus MCP Server

Сервер Model Context Protocol (MCP), который позволяет ИИ-ассистентам взаимодействовать с OmniFocus на macOS через JXA (JavaScript for Automation).

Возможности

Этот MCP-сервер предоставляет доступ к функциям OmniFocus:

Управление задачами

• Список задач во входящих — просмотр и фильтрация задач во входящих (включая фильтрацию по нескольким тегам)

• Создание задач — добавление новых задач с полной поддержкой свойств (сроки, запланированные даты, теги, заметки, подзадачи, повторение)

• Обновление задач — изменение названия, заметки, сроков, флага, оценки, повторения или перемещение задачи в другой проект

• Завершение/отмена задач — пометка задач как выполненных или отменённых, по отдельности или пакетно

• Удаление задач — окончательное удаление задачи

• Обновление заметок задач — замена, очистка или добавление к заметке задачи

• Получение задач по сроку — поиск задач со сроком в заданном диапазоне

• Получение запланированных задач — поиск задач, запланированных в заданном диапазоне

• Получение отмеченных задач — список всех задач с флагом

• Добавление/удаление тегов у задач — управление тегами задач, по отдельности или пакетно

Управление проектами

• Список проектов — просмотр проектов с фильтрацией по статусу

• Получение задач проекта — список всех задач, принадлежащих проекту

• Создание проектов — новые проекты с указанием папки, статуса, сроков, последовательного режима, интервала проверки

• Обновление проектов — изменение названия, заметки, статуса, флага, сроков, последовательного режима, интервала проверки

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

• Обновление заметок проектов — замена, очистка или добавление к заметке проекта

• Получение проектов для проверки — поиск проектов, требующих проверки, опционально с их незавершёнными задачами

• Пометка проекта проверенным — обновление статуса проверки и даты следующей проверки

• Пакетная пометка проверенным — эффективная проверка нескольких проектов сразу

Организация

• Список папок — просмотр иерархии папок

• Создание/переименование/удаление папок — управление деревом папок (включая вложенные папки)

• Список тегов — просмотр всех тегов

• Список перспектив — просмотр встроенных и пользовательских перспектив

• Получение задач перспективы — список задач, отображаемых в конкретной перспективе

Поиск

• Универсальный поиск — поиск по задачам, проектам, папкам и тегам

Свойства безопасности

• Нет «тихого победителя» при совпадении имён. OmniFocus позволяет двум проектам (или задачам) иметь одинаковое имя. Поиск по имени собирает все совпадения и завершается ошибкой с указанием идентификаторов, если совпадений больше одного, — так что переименование, перемещение или удаление никогда не затронет не тот элемент, сообщая при этом об успехе.

• Мутации проверяются. Операции, которые JXA может выполнить «тихо» неудачно (в частности, перемещение задачи между проектами), считывают результат в том же скрипте, — так что неудачное перемещение сообщается как ошибка, а не как успех.

Related MCP server: OmniFocus MCP Server

Требования

• macOS (OmniFocus существует только для macOS/iOS, и этот сервер использует JXA)

• OmniFocus 3+ установлен

• Node.js 18+

• Разрешения автоматизации включены для вашего терминала или клиентского приложения

Установка

1. Клонируйте или скачайте этот репозиторий:

   cd omnifocus-mcp-server

2. Установите зависимости:

   npm install

3. Соберите TypeScript:

   npm run build

4. Настройте ваш MCP-клиент для использования сервера (см. раздел «Конфигурация» ниже)

Конфигурация

Claude Desktop

Добавьте в файл конфигурации Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "omnifocus": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/omnifocus-mcp-server/dist/index.js"]
    }
  }
}

Используйте абсолютный путь к бинарнику node. Голый "node" разрешается относительно PATH графической сессии, куда не входят shims Homebrew или менеджера версий, — поэтому сервер не запустится с ошибкой вида «server unreachable», хотя из вашего терминала он работает нормально. Узнайте свой путь командой which node.

Другие MCP-клиенты

Сервер по умолчанию использует stdio-транспорт, поэтому настройте клиент на запуск:

node /path/to/omnifocus-mcp-server/dist/index.js

Удалённый доступ (HTTP-транспорт)

Для удалённых клиентов — в первую очередь пользовательских коннекторов claude.ai, через которые приложение Claude для iOS обращается к MCP-серверам, — сервер может работать как конечная точка Streamable HTTP:

MCP_TRANSPORT=http \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
node /path/to/omnifocus-mcp-server/dist/index.js

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

Конечная точка MCP — /mcp. Аутентификация принимает либо заголовок Authorization: Bearer <token>, либо токен как сегмент пути (/mcp/<token>) для клиентов, которые не умеют отправлять кастомные заголовки. GET /health доступен без аутентификации.

Доступ из claude.ai / приложения iOS. Пользовательские коннекторы подключаются из облака Anthropic (не с вашего устройства), поэтому конечная точка должна быть публично доступна по HTTPS. Для этого подойдёт Cloudflare Tunnel или Tailscale Funnel — в обоих случаях локальный процесс устанавливает исходящее соединение, так что открывать порты не нужно. (Обычный Tailscale, без Funnel, не подходит: он достаёт только до вашей собственной tailnet, а облако Anthropic в ней не находится.) При желании можно ограничить доступ диапазоном исходящих IP-адресов Anthropic (160.79.104.0/21) в правиле WAF Cloudflare.

Интерфейс коннекторов claude.ai и Claude Desktop (в отличие от «сырой» MCP-конфигурации или прямого API-клиента) всегда выполняет полный OAuth-цикл, прежде чем обратиться к удалённому серверу, — статический токен сам по себе, даже встроенный в URL, он не принимает. Установите MCP_PUBLIC_URL на публичный адрес вашего туннеля, чтобы включить слой самовыпущенного OAuth, который удовлетворяет этому требованию и при этом продолжает ограничивать доступ тем же статическим секретом (как — см. oauth.ts / CLAUDE.md). После этого добавьте коннектор в Настройки → Коннекторы, используя URL с токеном в пути (https://your-tunnel-host/mcp/<token>) — шаг «Connect» выполнит OAuth-рукопожатие автоматически. Если ваш туннель также проксирует / на другой локальный сервис, убедитесь, что /authorize, /token, /register и /.well-known/* направляются на этот сервер, — иначе OAuth-запросы до него просто не дойдут.

Mac должен оставаться включённым с запущенным OmniFocus (caffeinate -s или Amphetamine).

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

Два клиента одновременно — не работают. Воспроизводится запуском двух параллельных последовательностей initialize→tools/list на публичную конечную точку: один стабильно получает 404. Базовый MCP SDK привязывает один транспорт к общему экземпляру сервера, поэтому проигравшая сессия вытесняется, и её выполняющийся запрос либо получает 404, либо зависает. Исправление требует создания экземпляра McpServer на каждую сессию вместо текущего паттерна с регистрацией на синглтоне; в планах этого нет. Подробности — в CLAUDE.md.

Диагностика клиента с ошибкой «не могу подключиться». Клиенты сворачивают любую удалённую ошибку в одно расплывчатое сообщение, поэтому читайте лог этого сервера (StandardErrorPath вашего launch-агента), а не формулировку клиента, — код статуса показывает, какая из трёх несвязанных проблем произошла:

Если в логе вообще ничего нет, запрос до этого сервера не дошёл: проверяйте сопоставление путей в туннеле, а не этот код.

Разрешения

При первом использовании macOS спросит разрешение на автоматизацию:

1. Перейдите в Системные настройки → Конфиденциальность и безопасность → Конфиденциальность → Автоматизация

2. Включите разрешение для вашего терминала или Claude Desktop на управление OmniFocus

Справочник инструментов

Все 31 инструмент перечислены ниже, сгруппированы по областям.

omnifocus_list_inbox

Список задач во входящих, опционально с фильтрацией по тегам.

{
  "includeCompleted": false,
  "limit": 50,
  "tags": ["Work", "Urgent"],
  "tagMatchMode": "all"
}

tagMatchMode принимает значения "all" (у задачи есть все перечисленные теги; по умолчанию), "any" (хотя бы один) или "none" (ни одного). Он применяется только при заданном tags. Те же два параметра работают в omnifocus_get_due_tasks, omnifocus_get_flagged_tasks и omnifocus_get_planned_tasks.

omnifocus_list_projects

Список проектов с фильтрацией.

{
  "status": "active",
  "folderName": "Work",
  "limit": 50
}

omnifocus_get_project_tasks

Получение всех задач, принадлежащих одному проекту.

{
  "projectId": "abc123",
  "includeCompleted": false,
  "limit": 100
}

omnifocus_create_project

Создание проекта, опционально внутри папки.

{
  "name": "Website redesign",
  "note": "Q1 initiative",
  "folderName": "Work",
  "dueDate": "2024-03-31T17:00:00",
  "deferDate": "2024-01-15T09:00:00",
  "flagged": false,
  "sequential": false,
  "status": "active",
  "reviewIntervalDays": 7
}

status может быть "active" (по умолчанию), "on hold", "done" или "dropped". sequential: false (по умолчанию) делает проект параллельным.

omnifocus_update_project

Обновление свойств проекта. Определите проект по projectId или projectName (ID имеет приоритет).

{
  "projectId": "abc123",
  "name": "Website redesign v2",
  "status": "on hold",
  "flagged": true,
  "dueDate": null,
  "sequential": true,
  "reviewIntervalDays": 14
}

Передайте null для note, dueDate или deferDate, чтобы очистить их. Проект нельзя переместить в другую папку (ограничение JXA).

omnifocus_delete_project

Удаление проекта и его задач. Определите проект по projectId или projectName (ID имеет приоритет).

{
  "projectId": "abc123"
}

omnifocus_list_folders

Получить список всех папок.

{
  "status": "active",
  "limit": 50
}

omnifocus_create_folder

Создать папку, на верхнем уровне или вложенную.

{
  "name": "Clients",
  "parentFolderName": "Work"
}

omnifocus_update_folder

Переименование папки. Определите папку по folderId или folderName (ID имеет приоритет). Папку нельзя переместить в другую папку (ограничение JXA).

{
  "folderName": "Clients",
  "name": "Key clients"
}

omnifocus_delete_folder

Удалить папку и всё её содержимое. Определите папку по folderId или folderName (ID имеет приоритет).

{
  "folderId": "abc123"
}

omnifocus_list_tags

Получить список всех тегов.

{
  "status": "active",
  "limit": 50
}

omnifocus_list_perspectives

Получить список перспектив (встроенных и пользовательских).

{
  "limit": 50
}

omnifocus_get_perspective_tasks

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

{
  "perspectiveName": "Next",
  "limit": 50
}

omnifocus_create_task

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

{
  "name": "Review quarterly report",
  "note": "Check all sections",
  "projectName": "Work",
  "dueDate": "2024-12-31T17:00:00",
  "deferDate": "2024-12-01T09:00:00",
  "plannedDate": "2024-12-15T09:00:00",
  "flagged": true,
  "estimatedMinutes": 60,
  "tagNames": ["Review", "Important"],
  "parentTaskId": "xyz789",
  "recurrence": {
    "frequency": "weekly",
    "interval": 1,
    "daysOfWeek": ["Monday", "Thursday"],
    "repeatFrom": "due-date"
  }
}

Запланированная дата и срок выполнения:

• dueDate: срок, когда задача должна быть выполнена (дедлайн)

• plannedDate: дата, когда вы планируете работать над задачей (планирование)

• Это различие важно для разделения дедлайнов и запланированного времени работы

Повторение: frequency может быть "daily", "weekly", "monthly" или "yearly". Для еженедельных повторений используйте daysOfWeek, для ежемесячных — dayOfMonth (1-31), для ежегодных — monthOfYear (1-12). repeatFrom может быть "due-date" (по умолчанию) или "completion-date".

Подзадачи: передайте parentTaskId, чтобы создать задачу как дочернюю по отношению к существующей задаче.

omnifocus_update_task

Обновление существующей задачи. Определите задачу по taskId или taskName (ID имеет приоритет).

{
  "taskId": "abc123",
  "name": "Review quarterly report (final)",
  "note": null,
  "dueDate": "2024-12-20T17:00:00",
  "flagged": true,
  "estimatedMinutes": 45,
  "projectName": "Work"
}

• Передайте null для note, dueDate, deferDate или plannedDate, чтобы очистить их; estimatedMinutes: 0 очищает оценку.

• projectId / projectName перемещает задачу в указанный проект (подзадачи переносятся вместе с ней). Перемещение затем проверяется, поэтому сбой сообщается как ошибка, а не как ложный успех.

• recurrence принимает тот же объект, что и create_task; recurrence: null или clearRecurrence: true отключает повторение.

omnifocus_delete_task

Удалить задачу. Определите задачу по taskId или taskName (ID имеет приоритет).

{
  "taskId": "abc123"
}

omnifocus_update_task_note

Заменить, очистить или дополнить заметку задачи. Определите задачу по taskId или taskName (ID имеет приоритет).

{
  "taskId": "abc123",
  "note": "Added after the call.",
  "append": true
}

Пустая строка note очищает заметку.

omnifocus_complete_task

Отметить задачу как выполненную или отброшенную. Вы можете указать задачу по ID или имени.

{
  "taskId": "abc123",
  "action": "complete"
}

Или используя имя задачи:

{
  "taskName": "Write documentation",
  "action": "complete"
}

Действие может быть "complete" (по умолчанию) или "drop". Если указаны оба параметра — taskId и taskName, — приоритет имеет taskId.

Отбрасывание повторяющейся задачи сначала очищает правило её повторения, поэтому серия действительно останавливается, а не переходит к следующему вхождению.

omnifocus_batch_complete_task

Завершить или отбросить до 100 задач по ID одним вызовом.

{
  "taskIds": ["id1", "id2", "id3"],
  "action": "complete"
}

omnifocus_add_tag_to_task

Добавить тег к задаче. Вы можете указать задачу по ID или по имени.

{
  "taskId": "abc123",
  "tagName": "Urgent"
}

Или используя имя задачи:

{
  "taskName": "Write report",
  "tagName": "Urgent"
}

Если указаны оба параметра — taskId и taskName, приоритет имеет taskId.

omnifocus_remove_tag_from_task

Удалить тег из задачи. Вы можете указать задачу по ID или по имени.

{
  "taskId": "abc123",
  "tagName": "Urgent"
}

Или используя имя задачи:

{
  "taskName": "Old task",
  "tagName": "Done"
}

Если указаны оба параметра — taskId и taskName, приоритет имеет taskId.

omnifocus_batch_add_tag

Добавить один существующий тег к до 100 задачам по ID.

{
  "taskIds": ["id1", "id2", "id3"],
  "tagName": "Urgent"
}

omnifocus_batch_remove_tag

Удалить один тег из до 100 задач по ID.

{
  "taskIds": ["id1", "id2", "id3"],
  "tagName": "Urgent"
}

omnifocus_update_project_note

Заменить, очистить или дополнить заметку проекта. Определите проект по projectId или projectName (ID имеет приоритет).

{
  "projectName": "Website redesign",
  "note": "Kickoff moved to March.",
  "append": false
}

omnifocus_search

Поиск по OmniFocus.

{
  "query": "report",
  "searchType": "all",
  "limit": 20
}

omnifocus_get_due_tasks

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

{
  "daysAhead": 7,
  "includeOverdue": true,
  "limit": 50
}

omnifocus_get_flagged_tasks

Получить задачи с флагом.

{
  "includeCompleted": false,
  "limit": 50
}

omnifocus_get_planned_tasks

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

{
  "daysAhead": 7,
  "includeOverdue": true,
  "limit": 50
}

omnifocus_get_projects_for_review

Получить проекты, которые нуждаются в проверке, на основе их следующей даты проверки. Идеально подходит для практиков GTD, следующих рабочему процессу проверки.

{
  "daysAhead": 0,
  "status": "active",
  "limit": 50,
  "includeTasks": true,
  "taskLimit": 50
}

Параметры:

• daysAhead: на сколько дней заглядывать вперёд (0 — только просроченные проверки)

• status: фильтр по статусу проекта ("active", "done", "dropped", "onHold", "all")

• limit: максимальное количество возвращаемых проектов (1-500)

• includeTasks: включать незавершённые задачи каждого проекта в результате (по умолчанию false) — это превращает один проход проверки в один вызов вместо одного последующего вызова на проект

• taskLimit: максимальное количество задач на проект, когда includeTasks равен true (1-200, по умолчанию 50)

Каждый проект также возвращает reviewInterval и lastReviewDate.

omnifocus_mark_project_reviewed

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

{
  "projectId": "abc123"
}

Или используя имя проекта:

{
  "projectName": "Weekly Review"
}

С собственным интервалом проверки:

{
  "projectName": "Work Project",
  "reviewIntervalDays": 14
}

Параметры:

• projectId или projectName: идентифицирует проект (ID имеет приоритет)

• reviewIntervalDays (необязательно): собственный интервал проверки в днях. Если не указано, используется существующий интервал проверки проекта.

omnifocus_batch_mark_reviewed

Отметить несколько проектов как проверенные одной эффективной операцией.

{
  "projectIds": ["id1", "id2", "id3"]
}

С собственным интервалом проверки для всех:

{
  "projectIds": ["id1", "id2", "id3"],
  "reviewIntervalDays": 7
}

Параметры:

• projectIds: массив ID проектов для отметки как проверенных (1-100 проектов)

• reviewIntervalDays (необязательно): собственный интервал проверки, применяемый ко всем проектам

Возвращает сводку с результатами:

• количество успешных проверок

• количество ошибок

• полные данные проектов для успешных проверок

• сведения об ошибках для любых сбоев

Форматы дат

Все даты используют формат ISO 8601: YYYY-MM-DDTHH:mm:ss

Примеры:

• 2024-12-31T17:00:00 — 31 декабря 2024 года в 17:00

• 2024-06-15T09:00:00 — 15 июня 2024 года в 9:00

Обработка ошибок

Сервер предоставляет понятные сообщения об ошибках для типичных ситуаций:

• OmniFocus не запущен: сначала запустите OmniFocus

• Отказано в доступе: включите разрешения автоматизации в Системных настройках

• Элемент не найден: указанный ID не существует

• Недопустимые параметры: проверьте формат и значения параметров

Разработка

Сборка

npm run build

Режим наблюдения

npm run dev

Тесты

npm test              # All unit tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report (thresholds enforced: 80% lines, 75% branches)

Интеграционные тесты в src/__tests__/integration.test.ts по умолчанию пропускаются: они требуют запущенного OmniFocus и изменяют вашу реальную базу данных.

Тестирование вручную

После сборки вы можете проверить с помощью:

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

Применение изменений к запущенному серверу (важно)

MCP-клиенты получают список инструментов один раз при подключении и кэшируют его на время сессии. Просто запуск npm run build не обновляет уже подключённый клиент — Node не перезагружает код на лету, и клиент не будет повторно запрашивать схему. После изменения инструментов/схем необходимо перезапустить сервер и заново подключить клиента:

1. Пересборка: npm run build

2. Перезапустите серверный процесс, чтобы он загрузил новый dist/:

   • LaunchAgent (HTTP-транспорт): launchctl kickstart -k gui/$(id -u)/com.sanderrobijns.omnifocus-mcp

   • Проверьте, что он отдаёт новую схему: lsof -nP -iTCP:3000 -sTCP:LISTEN должен показать свежезапущенный PID.

3. Переподключите каждого клиента, чтобы он повторно запросил tools/list:

   • Claude Code / Cowork: начать новую сессию (запущенная сессия сохраняет закэшированную схему всё время своей жизни).

   • Claude Desktop: закройте и откройте приложение заново (или выключите и включите сервер).

   • claude.ai / пользовательский Y коннектор Claude iOS: повторно синхронизируйте коннектор в Настройках → Коннекторы (коннектор кэширует список инструментов на своём уровне).

Пока клиент не переподключится, он продолжает показывать старую схему, даже если сервер уже отдаёт новую.

Лицензия

MIT

Благодарности

Создано с использованием:

• Model Context Protocol SDK

• OmniFocus JXA API