OmniFocus MCP Server

OmniFocus를 Claude 및 기타 MCP 호환 AI 어시스턴트에 연결하는 Model Context Protocol(MCP) 서버입니다.

개요

이 서버는 AI 어시스턴트와 OmniFocus 데이터베이스를 연결합니다. 자연스러운 대화를 통해 어시스턴트는 작업과 프로젝트를 조회, 생성, 편집, 삭제할 수 있으며, 대량 작업도 가능합니다. 이를 통해 할 수 있는 일들:

• 강의 계획서 PDF를 작업, 태그, 연기 날짜, 마감 날짜가 포함된 완전한 프로젝트로 변환

• 회의 기록을 일련의 행동 목록으로 전환

• 태그, 프로젝트, 폴더를 대화형으로 감사하고 재구성

• 작업, 프로젝트, 태그의 시각화 생성

• 단일 배치 작업으로 수십 개 항목 처리

Related MCP server: MCP OmniFocus

빠른 시작

사전 요구 사항

• OmniFocus가 설치된 macOS

• 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 클라이언트도 동일한 방식으로 작동합니다: stdio를 통해 npx -y omnifocus-mcp를 실행하세요.

예시 대화

특정 조회:

"이번 주에 마감인 플래그된 작업을 모두 보여줘"

"Work 폴더의 다음 행동은 무엇인가요?"

"각 프로젝트에 작업이 몇 개인지 세어줘"

재구성:

"모든 작업에 에너지 수준 태그가 있으면 좋겠어요. 태그가 없는 모든 작업 목록과 추가할 태그에 대한 제안을 보여주세요. 적절하다고 생각되는 변경은 제가 직접 하겠습니다. 그런 다음 OmniFocus에서 변경을 적용하세요."

어디서든 캡처:

"법치주의가 왜 중요한지에 대한 자세한 설명 감사합니다. 제 활동 프로젝트에 매주 대표에게 전화하라는 반복 작업을 추가해 주세요. 이 대화의 요약을 메모 필드에 포함하세요."

퍼스펙티브 작업:

"사용 가능한 퍼스펙티브는 무엇인가요?"

"내 Inbox 퍼스펙티브에 무엇이 있는지 보여줘"

기록 또는 PDF 처리:

"오늘 회의 기록을 붙여넣습니다. 분석해서 제게 할당된 조치 항목에 대한 작업을 OmniFocus에 만들어 주세요. 'Product Development' 프로젝트에 넣어 주세요."

도구

서버는 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: 같은 배치의 다른 항목이 참조할 수 있는 임시 ID

• 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 핸드셰이크 중 서버는 클라이언트에 사용 지침을 보냅니다 — 도구 선택 조언 (dump_database보다 query_omnifocus 선호), 필터 팁, 리소스 카탈로그. 구성이 필요 없습니다.

로깅: 서버는 MCP 로깅 프로토콜을 통해 구조화된 로그를 내보냅니다. 클라이언트는 logging/setLevel (debug, info, warning, error, ...)로 상세 수준을 조정할 수 있습니다. 스크립트 실행 시간과 오류는 자동으로 기록됩니다.

작동 방식

서버는 osascript를 통해 OmniFocus와 통신하며, 적절한 경우 JXA(JavaScript for Automation)와 OmniFocus에 내장된 Omni Automation(OmniJS)을 사용합니다. 공식 MCP TypeScript SDK를 기반으로 하며 stdio를 통해 클라이언트와 통신합니다.

공유 데몬

omnifocus-mcp를 실행하면 공유 백그라운드 데몬에 연결되는 작은 shim이 시작되며, 이미 실행 중이지 않으면 데몬을 시작합니다. 머신의 모든 클라이언트는 각각 독립적인 MCP 세션을 얻지만, 모두 그 단일 프로세스 안에서 실행됩니다.

여러 에이전트가 동시에 OmniFocus를 사용할 때 중요합니다. OmniFocus는 AppleEvents로 구동되는 단일 스레드 애플리케이션이며, 서버는 동시에 실행할 osascript 호출 수를 제한합니다. 각 클라이언트가 자체 서버를 실행할 때 그 제한은 프로세스별로 적용되었습니다. 즉, 클라이언트 10개는 하나의 앱을 대상으로 하는 10개의 독립적인 예산을 의미하여 AppleEvent 시간 초과가 발생했습니다. 하나의 프로세스를 공유하면 제한이 전역적으로 적용됩니다.

데몬은 0700 디렉토리(기본적으로 ~/.omnifocus-mcp/daemon-<version>.sock)의 Unix 도메인 소켓에서 수신하므로 접근은 파일 시스템에 의해 강제됩니다. 네트워크 포트도 토큰도 없습니다. 유휴 시간 동안 연결된 클라이언트가 없으면 스스로 종료되며, 소켓 옆의 daemon.log에 로그를 남깁니다.

소켓 이름에는 패키지 버전이 포함되어 있어 업그레이드 후 이전 버전의 데몬과 통신하는 일이 없습니다. 업그레이드 직후에는 두 개의 데몬이 잠시 보일 수 있습니다. 이전 데몬은 이미 연결된 클라이언트를 계속 서비스하다가 마지막 클라이언트가 연결을 끊으면 종료됩니다. 이전 데몬에 여전히 연결된 클라이언트는 인밴드로 알림을 받습니다. 새 데몬이 서비스하는 동안 모든 도구 결과에 한 줄의 업그레이드 알림이 포함되므로 누구도 다시 연결할 필요를 기억할 필요가 없습니다.

클라이언트 구성은 변경되지 않습니다. 데몬을 시작할 수 없는 경우(특이한 샌드박스, 읽기 전용 홈 디렉토리 등) shim은 이전 버전과 마찬가지로 프로세스 내에서 독립 실행형 서버를 실행하는 것으로 대체됩니다.

환경 변수

로드맵

• MCP prompt 지원

• 프로젝트 및 작업에 대한 알림 조작

• 기능 요청 및 알려진 문제는 GitHub issues를 참조하세요.

기여

기여를 환영합니다! 자유롭게 풀 리퀘스트를 제출해 주세요. 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