Skip to main content
Glama
Sign In
nucleus-apple-mcp

nucleus-apple-mcp

by zish-rob-crur
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

中文版

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

🔌 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/<build_id>/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

Related MCP server: macos-mcp-tools

🧰 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
nucleus-apple notes list-notes --query project --include-plaintext-excerpt --pretty

# Health
nucleus-apple health read-daily-metrics --date 2026-03-14 --pretty

The CLI mirrors the MCP tool surface and emits JSON, which makes it suitable for shell automation and agent skill workflows.

🔧 Add as an MCP server

This server uses the stdio transport (a local subprocess). The first run will compile the Swift sidecar.

Codex CLI

# Add the server (writes to ~/.codex/config.toml)
codex mcp add nucleus-apple -- uvx nucleus-apple-mcp

# Verify
codex mcp list

Claude Code

# Add the server (use --scope user to make it available globally)
claude mcp add --scope user nucleus-apple -- uvx nucleus-apple-mcp

# Verify
claude mcp list

You can also launch the server through the CLI:

nucleus-apple mcp serve

🪝 OpenClaw + Hermes Agent Skills

This repository includes reusable agent skills under skills/ for:

  • nucleus-apple-calendar

  • nucleus-apple-reminders

  • nucleus-apple-notes

  • nucleus-apple-health

Each skill depends on the nucleus-apple binary and is designed to be reused without changing the command surface.

If your agent supports repo-based skill install via chat, you can say:

install skill https://github.com/zish-rob-crur/nucleus-apple-mcp nucleus-apple-health

Available Tools

30 tools
calendar.create_eventC

Create a calendar event.

Inputs: calendar_id (required), title (required), start (required), end (required), +5 more. Returns: object

calendar.delete_eventB

Delete a calendar event.

Inputs: event_id (required), span. Returns: object

calendar.list_calendarsC

List event calendars.

Inputs: source_id, include_hidden. Returns: object

calendar.list_eventsB

List events within a time range.

Inputs: start (required), end (required), calendar_id, source_id, +2 more. Returns: object

calendar.list_sourcesA

List calendar sources/accounts.

Inputs: include_empty. Returns: object

calendar.update_eventC

Update an existing calendar event.

Inputs: event_id (required), span, calendar_id, title, +11 more. Returns: object

health.analyze_rangeA

Analyze a Health date range using exported daily snapshots only. Returns metric summaries, segment trends, notable days, and brief insights without reading raw samples.

Inputs: start_date (required), end_date (required), metric_keys, segment_count, +1 more. Returns: object

health.inspect_dayA

Inspect one day by combining the daily snapshot with the raw manifest, and explain metric/raw gaps.

Inputs: date (required), metric_keys, type_keys, storage_backend. Returns: object

health.list_changesA

List health sync commits after an optional cursor, with optional per-date raw type details from raw manifests.

Inputs: since_cursor, limit, include_raw_types, storage_backend. Returns: object

health.list_sample_catalogA

List known Health raw sample types, kinds, tags, and how they relate to daily metrics.

Inputs: no named parameters. Returns: object

health.read_daily_metricsA

Read one day's exported Health metrics snapshot from an S3-compatible object store.

Inputs: date (required), storage_backend. Returns: object

health.read_daily_rawA

Read one day's raw Health samples. Prefer health.read_samples for range queries and richer filtering.

Inputs: date (required), max_records, type_keys, tags, +5 more. Returns: object

health.read_range_metricsA

Read a date range of exported daily metrics using monthly indexes. Missing dates are reported, not treated as an error.

Inputs: start_date (required), end_date (required), storage_backend. Returns: object

health.read_samplesB

Read raw Health samples across one or more dates, filtered by type_keys/tags/kinds, with manifest-aware pagination.

Inputs: start_date (required), end_date, type_keys, tags, +6 more. Returns: object

notes.add_attachmentC

Add attachment(s) to a note from local file paths.

Inputs: note_id (required), attach_file (required). Returns: object

notes.create_noteC

Create a new note.

Inputs: folder_id, title, plaintext, markdown, +1 more. Returns: object

notes.delete_noteA

Delete a note.

Inputs: note_id (required). Returns: object

notes.get_noteB

Fetch a note with optional content and attachments.

Inputs: note_id (required), include_plaintext, include_body_html, include_attachments. Returns: object

notes.list_accountsB

List Notes accounts.

Inputs: no named parameters. Returns: object

notes.list_attachmentsB

List attachments for a note.

Inputs: note_id (required), include_shared. Returns: object

notes.list_foldersC

List Notes folders.

Inputs: account_id, parent_folder_id, recursive, include_shared, +1 more. Returns: object

notes.list_notesB

List notes (metadata-first).

Inputs: account_id, folder_id, query, include_plaintext_excerpt, +4 more. Returns: object

notes.save_attachmentB

Export an attachment to a file path.

Inputs: attachment_id (required), output_path (required), overwrite. Returns: object

notes.update_noteC

Update an existing note.

Inputs: note_id (required), title, allow_destructive, set_plaintext, +4 more. Returns: object

reminders.create_reminderC

Create a reminder.

Inputs: list_id (required), title (required), start, due, +3 more. Returns: object

reminders.delete_reminderB

Delete a reminder.

Inputs: reminder_id (required). Returns: object

reminders.list_listsC

List reminder lists.

Inputs: source_id, include_hidden. Returns: object

reminders.list_remindersC

List reminders by filters.

Inputs: start, end, due_start, due_end, +4 more. Returns: object

reminders.list_sourcesB

List reminder sources/accounts.

Inputs: include_empty. Returns: object

reminders.update_reminderB

Update an existing reminder.

Inputs: reminder_id (required), list_id, title, start, +10 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 30 tools

    Disambiguation5/5

    Tools are clearly separated by domain prefixes (calendar, health, notes, reminders) and specific verb-noun combinations within each domain, eliminating any ambiguity between tools.

    Naming Consistency5/5

    All tools follow a consistent pattern of domain prefix followed by verb_noun in snake_case, e.g., calendar.create_event, health.read_samples, notes.list_folders, providing a highly predictable naming scheme.

    Tool Count4/5

    With 30 tools across four distinct domains (calendar, health, notes, reminders), the count is above average but well-justified by the breadth of functionality, averaging 7.5 tools per domain which is reasonable for feature-rich integrations.

    Completeness5/5

    Each domain provides comprehensive CRUD-like operations plus additional utilities: calendar covers events/sources, health includes analysis and raw data reads, notes cover attachments and folders, and reminders cover lists/sources. No obvious gaps for typical use cases.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers