omnifocus-mcp

OmniFocus용 MCP 서버로, 전체 Omni Automation JavaScript API를 LLM 호출자에게 노출합니다.

macOS 전용입니다. OmniFocus가 같은 머신에서 실행 중이어야 합니다. 전체 구현은 osascript -l JavaScript를 통해 OmniFocus 내부에서 OmniJS 스니펫을 실행합니다. AppleScript 문자열 생성도, 스크립팅 사전 제약도 없습니다.

사전 요구 사항

• macOS (Omni Automation은 macOS 전용이며, 서버는 다른 플랫폼에서는 시작되지 않습니다)

• OmniFocus 설치 및 실행 상태

• Node.js ≥ 20

Related MCP server: OmniFocus MCP Server

설치

이 패키지는 npm에 @scardis/omnifocus-mcp로 게시되어 있습니다.

npx로 사용 (설치 불필요)

MCP 클라이언트 설정에 추가합니다 (예: Claude Desktop claude_desktop_config.json):

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

소스에서 직접

git clone https://github.com/steveardis/omnifocus-mcp.git
cd omnifocus-mcp
npm install
npm run build

그런 다음 MCP 클라이언트를 설정합니다:

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

사용 가능한 도구

읽기

쓰기

주소 지정 모델

이 서버가 반환하는 모든 엔티티에는 안정적인 id 필드(OmniFocus의 id.primaryKey)가 포함됩니다. 이후 호출에서는 이름 대신 이 ID를 사용하세요. 이름은 모호할 수 있지만 ID는 그렇지 않습니다.

이름은 있지만 ID가 없다면 resolve_name을 사용하세요. 이 도구는 목록을 반환합니다. 여러 후보가 반환되면 path 필드를 확인하고 쓰기 작업을 진행하기 전에 사용자에게 명확히 하도록 요청하세요.

다른 OmniFocus MCP 서버와의 비교

주목할 만한 대안이 두 가지 있습니다: themotionmachine/OmniFocus-MCP와 jqlts1/omnifocus-mcp-enhanced(위 프로젝트에서 파생되어 추가 도구가 포함된 버전)입니다.

스크립팅 API. 대안들은 JXA 스크립팅 사전 또는 AppleScript를 사용해 OmniFocus를 구동합니다. 이 서버는 단일 JXA 호출(Application('OmniFocus').evaluateJavascript())을 수행하고 모든 로직을 OmniFocus 내부에서 OmniJS(Omni Automation)로 실행합니다. 이를 통해 더 제한적인 스크립팅 사전 대신 전체 Omni Automation API 표면(반복 규칙, 검토 주기, 퍼스펙티브, 예측, 첨부 파일, URL 자동화 등)에 접근할 수 있습니다.

인자 주입. 대안들은 문자열 보간을 통해 osascript 명령을 구성하므로 이름에 포함된 아포스트로피, 따옴표, 백슬래시, 유니코드에서 문제가 발생할 수 있습니다. 이 서버는 모든 인자를 JSON.stringify로 직렬화하여 JS 리터럴로 주입합니다.

엔티티 주소 지정. 대안들은 주로 이름으로 엔티티를 참조합니다. 이 서버는 모든 엔티티에 대해 안정적인 id(id.primaryKey)를 반환하고 resolve_name을 제공하여 이름을 ID 후보로 매핑합니다. 이름이 모호할 때 조용히 하나를 선택하는 대신 전체 경로와 함께 모든 일치 항목을 반환합니다.

전체 CRUD. 이 서버는 작업, 프로젝트, 폴더, 태그의 생성, 편집, 완료, 드롭, 삭제, 이동을 지원하며, 반복 규칙과 OmniFocus 4의 계획 날짜도 지원합니다.

개발

# Type-check without building
npm run typecheck

# Run unit tests (no OmniFocus required)
npm test

# Build
npm run build

테스트

단위 테스트 (OmniFocus 불필요)

npm test

통합 테스트

⚠️ 통합 테스트는 실제 OmniFocus 데이터베이스를 대상으로 실행됩니다.

각 테스트 실행은 __MCP_TEST_<uuid>__라는 이름의 임시 최상위 폴더를 만들고 종료 시 삭제합니다. 테스트 실행이 종료 전에 중단된 경우 정리 스크립트를 실행하세요:

npm run test:cleanup-fixtures

⚠️ 동기화 경고: 기본적으로 통합 테스트는 테스트 픽스처가 다른 기기로 전파되는 것을 방지하기 위해 OmniFocus 동기화가 활성화된 경우 실행을 거부합니다. 먼저 OmniFocus 동기화를 비활성화하거나, MCP_TEST_ALLOW_SYNC=1을 설정하여 옵트인하세요(픽스처가 동기화됩니다):

# Default (refuses if sync enabled)
npm run test:integration

# With sync enabled (use carefully)
MCP_TEST_ALLOW_SYNC=1 npm run test:integration

오래된 테스트 픽스처 정리

npm run test:cleanup-fixtures

이 스크립트는 중단된 테스트 실행으로 OmniFocus에 남은 __MCP_TEST_*__ 폴더와 고아가 된 __mcp_*__ 프로젝트/태그를 모두 제거합니다.

기여

기여는 언제나 환영합니다! 시작 방법은 다음과 같습니다:

1. 저장소를 포크하고 클론합니다

2. 의존성 설치: npm install

3. 단위 테스트 실행 (OmniFocus 불필요): npm test

4. 통합 테스트 실행 (macOS + OmniFocus 필요): npm run test:integration

PR 제출 전

• npm run typecheck — 오류 없이 통과해야 함

• npm test — 모든 단위 테스트가 통과해야 함

• npm run test:integration — 모든 통합 테스트가 통과해야 함 (macOS 전용)

• 변경 사항은 집중적으로 유지 — PR당 하나의 기능 또는 수정

아키텍처 개요

서버는 osascript -l JavaScript를 통해 OmniFocus 내부에서 OmniJS 스니펫을 실행합니다. 각 도구는 세 개의 계층으로 구성됩니다:

• Schema (src/schemas/shapes.ts) — 입력 검증 및 출력 파싱을 위한 Zod 스키마

• Snippet (src/snippets/*.js) — OmniFocus 내부에서 실행되는 OmniJS 코드. 순수 ES5 JavaScript(import 없음, TypeScript 없음). 인자는 __ARGS__ 플레이스홀더를 통해 주입됩니다.

• Tool handler (src/tools/*.ts) — 입력 검증, runSnippet() 호출, 결과 파싱

새 도구를 추가할 때:

1. src/schemas/shapes.ts에서 입력/출력 스키마를 정의하고 src/schemas/index.ts에서 내보냅니다

2. src/snippets/에 OmniJS 스니펫을 생성합니다

3. src/runtime/snippetLoader.ts의 ALLOWED_SNIPPETS에 스니펫 이름을 추가합니다

4. src/tools/에 도구 핸들러를 생성하고 src/tools/index.ts에 등록합니다

5. 스키마에 대한 단위 테스트와 OmniFocus를 대상으로 실행되는 통합 테스트를 추가합니다

OmniJS 스니펫 작성

스니펫은 Node.js가 아닌 OmniFocus의 JavaScript 런타임 내부에서 실행됩니다. 주요 제약 사항:

• ES5 스타일 JavaScript — var, function(){} 사용, 이전 OmniFocus 버전에서는 화살표 함수 사용 불가

• import 없음 — 모든 OmniJS 전역 객체(flattenedTasks, flattenedProjects, moveTasks 등)를 직접 사용 가능

• JSON 반환 — 항상 return JSON.stringify({ ok: true, data: ... })

• 오류 패턴 — 브리지가 캐치하여 래핑하는 명명된 오류(NotFoundError, ValidationError)를 throw

라이선스

MIT