中文版

⚛️ 核心：macOS 生命上下文服务器

给你的AI代理一个海马体。

nucleus-apple-mcp 是一款模型上下文协议（MCP）服务器，旨在统一您在 macOS 上的数字生活。它允许 AI 代理（如 Claude Desktop、光标或自定义代理）安全地读取并与您的个人数据生态系统交互。

与脆弱的 PyObjC 桥不同，Nucleus 采用混合架构：一个 Python MCP 服务器，负责编排轻量级、通过 JIT 编译的原生 Swift 工作节点。这确保了类型安全、性能高且可靠的苹果原生 API 访问，同时保持通过 uvx 轻松分发。

关于产品概述和设置路径，请参见 docs/introducing-nucleus.md。 从App Store下载iOS应用：Nucleus Context Hub。

Terminal + MCP 演示：Nucleus 总结了从出口健康数据中出现的30天复苏趋势。

🔌 集成

✅ 可用（当前发行）

• ** 📅 日历：** 获取即将到来的日程表，检查可用性，并通过EventKit创建活动。
• ** ✅ 提醒：** 阅读待办任务并通过EventKit管理待办事项。
• ** 📝 笔记：** 通过 Notes.app（Apple Events）列表/搜索笔记、阅读内容以及添加/导出附件。

中文版

⚛️ 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