OmniFocus MCP 서버

macOS의 OmniFocus와 AI 어시스턴트가 상호작용할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다. JXA(JavaScript for Automation)를 사용합니다.

기능

이 MCP 서버는 OmniFocus의 다양한 기능에 접근할 수 있게 해줍니다:

작업 관리

• 받은 편지함 작업 나열 - 받은 편지함의 작업을 필터링하여 조회합니다(다중 태그 필터링 포함)

• 작업 생성 - 전체 속성을 지원하는 새 작업을 추가합니다(마감일, 예정일, 태그, 메모, 하위 작업, 반복)

• 작업 업데이트 - 이름, 메모, 날짜, 플래그, 예상 시간, 반복을 변경하거나 작업을 다른 프로젝트로 이동합니다

• 작업 완료/보류 - 작업을 개별적으로 또는 일괄로 완료 또는 보류 처리합니다

• 작업 삭제 - 작업을 영구적으로 제거합니다

• 작업 메모 업데이트 - 작업의 메모를 교체, 삭제 또는 추가합니다

• 기한 작업 조회 - 특정 기간 내에 마감되는 작업을 찾습니다

• 예정 작업 조회 - 특정 기간 내에 예정된 작업을 찾습니다

• 플래그 작업 조회 - 플래그가 지정된 모든 항목을 나열합니다

• 작업 태그 추가/제거 - 작업 태그를 개별적으로 또는 일괄로 관리합니다

프로젝트 관리

• 프로젝트 나열 - 상태 필터링으로 프로젝트를 조회합니다

• 프로젝트 작업 조회 - 특정 프로젝트에 속한 모든 작업을 나열합니다

• 프로젝트 생성 - 폴더 배치, 상태, 날짜, 순차 모드, 검토 주기를 지원하는 새 프로젝트를 만듭니다

• 프로젝트 업데이트 - 이름, 메모, 상태, 플래그, 날짜, 순차 모드, 검토 주기를 변경합니다

• 프로젝트 삭제 - 프로젝트와 그 작업을 제거합니다

• 프로젝트 메모 업데이트 - 프로젝트의 메모를 교체, 삭제 또는 추가합니다

• 검토 대상 프로젝트 조회 - 검토가 필요한 프로젝트를 찾습니다(미완료 작업 포함 여부 선택 가능)

• 프로젝트 검토 완료 표시 - 프로젝트의 검토 상태와 다음 검토 날짜를 업데이트합니다

• 일괄 검토 완료 표시 - 여러 프로젝트를 한 번에 효율적으로 검토 처리합니다

조직 관리

• 폴더 나열 - 폴더 계층 구조를 조회합니다

• 폴더 생성/이름 변경/삭제 - 폴더 트리를 관리합니다(중첩 폴더 포함)

• 태그 나열 - 모든 태그를 조회합니다

• 원근법 나열 - 기본 및 사용자 정의 원근법을 조회합니다

• 원근법 작업 조회 - 특정 원근법에 표시되는 작업을 나열합니다

검색

• 통합 검색 - 작업, 프로젝트, 폴더, 태그를 아우르는 검색을 수행합니다

안전 속성

• 중복 이름에 대한 무음 실패 없음. OmniFocus는 두 프로젝트(또는 작업)가 같은 이름을 공유할 수 있습니다. 이름 조회는 모든 일치 항목을 수집하고 일치 항목이 둘 이상일 경우 해당 ID와 함께 실패하므로, 이름 변경·이동·삭제가 성공으로 보고되면서 잘못된 항목에 적용되는 일이 없습니다.

• 변경 사항 검증. 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"는 GUI 세션의 PATH를 기준으로 해석되는데, 여기에는 Homebrew나 버전 관리자의 shim이 포함되지 않으므로 터미널에서는 정상 작동해도 서버가 "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: <token> 헤더 또는 경로 세그먼트(/mcp/<token>)를 통해 이루어집니다 — 사용자 정의 헤더를 보낼 수 없는 클라이언트를 위한 방식입니다. GET /health는 인증 없이 접근 가능합니다.

claude.ai / iOS 앱에서 접근하기. 커스텀 커넥터는 Anthropic의 클라우드(사용자 기기가 아님)에서 연결하므로, 엔드포인트는 HTTPS로 공개적으로 도달 가능해야 합니다. Cloudflare Tunnel 또는 Tailscale Funnel이 모두 이 용도로 작동합니다 — 어느 쪽이든 로컬 프로세스가 아웃바운드 연결을 만들므로 열린 포트가 필요 없습니다. (일반 Tailscale은 불가능합니다: 그건 자신의 tailnet에만 도달하며 Anthropic의 클라우드는 그 안에 없습니다.) 선택적으로 Cloudflare WAF 규칙에서 Anthropic의 아웃바운드 IP 범위(160.79.104.0/21)로 접근을 제한할 수 있습니다.

claude.ai 및 Claude Desktop의 "Connectors" UI는 원시 MCP 구성/직접 API 클라이언트와 달리, 원격 서버를 호출하기 전에 항상 전체 OAuth 핸드셰이크를 수행합니다 — URL에 토큰이 포함되어 있어도 정적 토큰만으로는 받아들이지 않습니다. MCP_PUBLIC_URL을 터널의 공개 원본으로 설정하면 동일한 정적 비밀키로 접근을 제어하면서 이 요구를 충족하는 자체 발급 OAuth 계층이 활성화됩니다(방법은 oauth.ts / CLAUDE.md 참조). 설정 후에는 Settings → Connectors에서 경로-토큰 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 또는 중단(hang)됩니다. 이를 해결하려면 현재의 단일 인스턴스(singleton) 등록 패턴 대신 세션별 McpServer 인스턴스가 필요합니다; 현재 계획되어 있지 않습니다. 자세한 내용은 CLAUDE.md를 참조하세요.

"연결할 수 없음" 클라이언트 문제 해결. 클라이언트는 모든 원격 오류를 하나의 모호한 메시지로 압축하므로, 클라이언트의 문구 대신 이 서버의 로그(런치 에이전트의 StandardErrorPath)를 읽으세요 — 상태 코드가 서로 무관한 세 가지 문제 중 어떤 것인지 알려줍니다:

로그에 아무것도 나타나지 않는다면 요청이 이 서버에 도달하지 않은 것입니다: 이 코드가 아니라 터널의 경로 매핑을 확인하세요.

권한

최초 사용 시 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
}

note, dueDate 또는 deferDate에 null을 전달하면 해당 값을 지웁니다. 프로젝트는 다른 폴더로 이동할 수 없습니다(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"
}

• note, dueDate, deferDate 또는 plannedDate에 null을 전달하면 지웁니다. 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

한 번의 호출로 ID로 최대 100개의 작업을 완료 또는 중단합니다.

{
  "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

ID로 최대 100개의 작업에 기존 태그 하나를 추가합니다.

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

omnifocus_batch_remove_tag

ID로 최대 100개의 작업에서 태그 하나를 제거합니다.

{
  "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 - 2024년 12월 31일 오후 5:00

• 2024-06-15T09:00:00 - 2024년 6월 15일 오전 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 / Claude iOS 사용자 정의 커넥터: 설정 → 커넥터에서 커넥터를 다시 동기화합니다(커넥터 수준에서 도구 목록을 캐시합니다).

클라이언트가 다시 연결될 때까지 서버가 이미 새 스키마를 제공하더라도 이전 스키마를 계속 표시합니다.

라이선스

MIT

크레딧

다음을 사용하여 구축:

• Model Context Protocol SDK

• OmniFocus JXA API