한국어

Nu️ Nucleus : macOS Life Context Server

** AI 에이전트를 Hippocampus. **

nucleus-apple-mcp는 macOS에서 디지털 라이프를 unify 위해 설계된 Model Context Protocol (MCP) 서버입니다. 그것은 AI 에이전트 (클래드 데스크톱, 커서, 또는 사용자 정의 에이전트와 같은) 개인 데이터 생태계와 안전하게 읽고 상호 작용 할 수 있습니다.

fragile PyObjC 브리지와는 달리, Nucleus는 하이브리드 아키텍처를 사용합니다. Python MCP 서버는 경량, JIT-compiled native Swift 노동자를 관용했습니다. 이것은 Apple의 기본 API에 대한 Type-safe, performant 및 신뢰할 수있는 액세스를 보장하고 uvx를 통해 쉽게 배포 할 수 있습니다.

제품 개요 및 설정 경로의 경우 docs/introducing-nucleus.md를 참조하십시오. 앱 스토어에서 iOS 앱 다운로드: Nucleus Context Hub.

터미널 + MCP 데모 : Nucleus는 수출 된 건강 데이터에서 30 일 복구 추세를 요약합니다.

은 통합

✅ (현재 릴리스)

• ** RUS 캘린더:** 예정된 일정, 체크 아웃 가능 여부 및 EventKit를 통해 이벤트를 만듭니다.
• ** ✅ Reminders:** [T3]] 을 통해 당신의 to-do 목록을 읽습니다. *** 주:** List/search notes, read content, and add/export attachments via Notes.app (애플 이벤트).

中文版

⚛️ Nucleus: macOS Life Context Server

Give your AI Agent a Hippocampus.

nucleus-apple-mcp is a Model Context Protocol (MCP) server designed to unify your digital life on macOS. It allows AI agents (like Claude Desktop, Cursor, or custom agents) to securely read and interact with your personal data ecosystem.

Unlike fragile PyObjC bridges, Nucleus uses a hybrid architecture: a Python MCP server that orchestrates lightweight, JIT-compiled native Swift workers. This ensures type-safe, performant, and reliable access to Apple’s native APIs while remaining easily distributable via uvx.

For a product overview and setup path, see docs/introducing-nucleus.md. Download the iOS app from the App Store: Nucleus Context Hub.

Terminal + MCP demo: Nucleus summarizes a 30-day recovery trend from exported Health data.

🔌 Integrations

✅ Available (current release)

• 📅 Calendar: Fetch upcoming schedules, check availability, and create events via EventKit.
• ✅ Reminders: Read pending tasks and manage your to-do lists via EventKit.
• 📝 Notes: List/search notes, read content, and add/export attachments via Notes.app (Apple Events).
• ❤️ Health: Read exported Apple Health metrics and raw samples from an S3-compatible object store.

🏗 Architecture

• Python: Handles the MCP protocol, request routing, and distribution (pip/uv).
• Swift: Embedded source code acts as a “Sidecar.” It is compiled locally on the first run (using SwiftPM swift build) to interface directly with macOS private frameworks, bypassing the limitations of Python-Objective-C bridges.

📦 Swift Sidecar Layout

• Swift Package Root: src/nucleus_apple_mcp/sidecar/swift/ (includes Package.swift; CLI uses swift-argument-parser)
• Build Cache (macOS): ~/Library/Caches/nucleus-apple-mcp/sidecar//nucleus-apple-sidecar
• Optional Env Vars: NUCLEUS_APPLE_MCP_CACHE_DIR (overrides cache directory), NUCLEUS_SWIFT (swift path), NUCLEUS_SWIFTC (swiftc path)

🚀 Usage

# Run the CLI directly.
uvx --from nucleus-apple-mcp nucleus-apple health list-sample-catalog

# Or run the MCP server.
uvx nucleus-apple-mcp

🧰 CLI

Install the package once and use the unified nucleus-apple command:

uv tool install nucleus-apple-mcp

Examples:

# Calendar
nucleus-apple calendar list-events --start 2026-03-15T09:00:00+08:00 --end 2026-03-15T18:00:00+08:00 --pretty

# Reminders
nucleus-apple reminders list-reminders --due-end 2026-03-20 --pretty

# Notes