iwatch-mcp

Real-time Apple Watch heart rate monitoring via the Model Context Protocol.

Heart rate data flows: Apple Watch → iPhone → Mac (via iCloud/HealthKit).
This server reads it from macOS HealthKit and exposes it as MCP tools to Claude or any MCP client.

Architecture

Claude / MCP client
      │  MCP (stdio)
      ▼
iwatch-mcp  (Python)          ← pip install
      │  subprocess
      ▼
HealthKitHelper  (Swift CLI)  ← ./healthkit-helper/build.sh
      │  HealthKit API
      ▼
macOS HealthKit database      ← synced from Apple Watch via iPhone

Prerequisites

Requirement	Notes
macOS 13+	HealthKit for Mac requires Ventura or later
Xcode	Installed from the App Store (needed to build Swift helper)
Apple Developer account	Required to sign the binary with HealthKit entitlement
Apple Watch paired	Data syncs through iPhone → iCloud → Mac
Python 3.11+	For the MCP server

Why signing is required: com.apple.developer.healthkit is a restricted entitlement.
macOS will reject HealthKit calls from binaries not signed with a valid Apple Developer certificate.

Setup

1 — Build and sign the Swift helper

cd healthkit-helper
./build.sh

build.sh automatically finds the best signing identity in your keychain
(prefers "Developer ID Application", falls back to "Apple Development").

To list available signing identities:

security find-identity -v -p codesigning

To sign manually with a specific identity:

codesign --force \
         --sign "Apple Development: you@example.com (TEAMID)" \
         --entitlements HealthKitHelper.entitlements \
         --options runtime \
         .build/release/HealthKitHelper

2 — Grant HealthKit access

Run the helper once to trigger the macOS permission dialog:

./healthkit-helper/.build/release/HealthKitHelper latest

When prompted, open System Settings → Privacy & Security → Health and enable
HealthKitHelper for reading heart rate data.

3 — Install the Python MCP server

pip install -e .

Or with pipx (recommended for isolation):

pipx install .

4 — Connect to Claude

Add to ~/Library/Application Support/Claude/claude_desktop_config.json.

Option A — venv entrypoint (recommended):

{
  "mcpServers": {
    "iwatch": {
      "command": "/Users/ehuang/Repos/iwatch-mcp/.venv/bin/iwatch-mcp"
    }
  }
}

Option B — run via python module:

{
  "mcpServers": {
    "iwatch": {
      "command": "/Users/ehuang/Repos/iwatch-mcp/.venv/bin/python",
      "args": ["-m", "iwatch_mcp.server"]
    }
  }
}

Restart Claude Desktop. The iwatch server will appear in the MCP panel.

MCP Tools

get_heart_rate

Returns the most recent heart rate sample from HealthKit.

Example response:

{
  "bpm": 72.0,
  "timestamp": "2025-06-15T14:32:00.000Z",
  "source": "Apple Watch",
  "device": "Apple Watch Series 9"
}

---

stream_heart_rate(duration_seconds: int = 30)

Collects readings over a rolling time window.
Immediately returns any buffered readings from the last 5 minutes, then
watches for new samples for duration_seconds seconds.

Note: Apple Watch syncs over iCloud — "real-time" latency is typically 10–60 seconds.

Example response:

[
  {"bpm": 68.0, "timestamp": "2025-06-15T14:31:45.000Z", "source": "Apple Watch", "device": "Apple Watch Series 9"},
  {"bpm": 70.0, "timestamp": "2025-06-15T14:32:00.000Z", "source": "Apple Watch", "device": "Apple Watch Series 9"}
]

---

get_heart_rate_history(hours: float = 24.0)

Retrieves and summarises historical heart rate data.

Example response:

{
  "count": 42,
  "hours_requested": 24.0,
  "min_bpm": 52.0,
  "max_bpm": 143.0,
  "avg_bpm": 71.3,
  "first_timestamp": "2025-06-14T14:35:00.000Z",
  "last_timestamp": "2025-06-15T14:32:00.000Z",
  "samples": [...]
}

MCP Resource

healthkit://heart-rate/status — reports whether the helper binary is built and ready.

Environment Variables

Variable	Default	Description
HEALTHKIT_HELPER_PATH	healthkit-helper/.build/release/HealthKitHelper	Override binary location

Troubleshooting

"HealthKit is not available on this device"

HealthKit requires macOS 13+ on Apple Silicon (M1/M2/M3 Mac). It is not available on Intel Macs.

"Auth failed" / empty results after first run

1. Open System Settings → Privacy & Security → Health
2. Scroll to find HealthKitHelper and toggle on Heart Rate
3. Also ensure the Health app is open and signed into iCloud

No data / stale data

Health data syncs from Apple Watch through iPhone. Make sure:

• iPhone is nearby and connected (Wi-Fi or Bluetooth to Mac)
• iCloud Drive is enabled on both iPhone and Mac
• Health app is signed into the same Apple ID on Mac

Binary not signed / HealthKit permission denied

HealthKit requires a real Apple Developer certificate. Ad-hoc signing (-s -) does not work
for the com.apple.developer.healthkit entitlement. You need either:

• A paid Apple Developer Program membership ($99/year)
• Or a free Apple Developer account (limited entitlements — HealthKit is included for device testing)

Test the helper directly

# Latest reading
./healthkit-helper/.build/release/HealthKitHelper latest

# 24 hours of history
./healthkit-helper/.build/release/HealthKitHelper history 24

# Stream for 60 seconds
./healthkit-helper/.build/release/HealthKitHelper stream 60