Skip to main content
Glama
Edplayerone

iwatch-mcp

by Edplayerone
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

Related MCP server: Apple Health Shortcuts MCP

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

Available Tools

3 tools
get_heart_rateA

Get the most recent heart rate reading from Apple Watch.

Returns: JSON object with fields: bpm - heart rate in beats per minute timestamp - ISO-8601 UTC time of the reading source - device/app that recorded the reading device - Apple Watch model (may be null)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description lacks details on error conditions, permissions, or what happens if no data is available. The return format is described but not behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Short, front-loaded with purpose, and efficiently lists return fields without extraneous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and an output schema (assumed), description explains return fields fully. For a simple getter, it is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters; schema coverage is 100% vacuously. Baseline for 0 params is 4. Description adds no extra parameter info necessary.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it gets the most recent heart rate reading from Apple Watch. Siblings get_heart_rate_history and stream_heart_rate indicate distinct use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for the latest reading, but does not explicitly state when to use this vs siblings or mention any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_heart_rate_historyA

Retrieve heart rate history stored in macOS HealthKit.

Returns all samples recorded within the past N hours, sorted oldest-first. Data comes from Apple Watch and any other HealthKit sources (e.g. Workout app).

Args: hours: How many hours of history to fetch (default 24, max ~168 for a week).

Returns: JSON array of heart rate samples, each with bpm / timestamp / source / device.

ParametersJSON Schema
NameRequiredDescriptionDefault
hoursNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully covers behavior: returns all samples in past N hours, sorted oldest-first, from Apple Watch and HealthKit sources. It also describes the return format (JSON with bpm/timestamp/source/device).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (5 sentences) with a clear front-loaded purpose, followed by parameter details and return format. Every sentence contributes meaning without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple one-parameter tool, the description is complete: it explains the function, input, output, data sources, and constraints. The existence of an output schema is acknowledged but not required for completeness here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The parameter 'hours' is explained with its meaning, default, and maximum value, adding significant value beyond the schema which only provides type and default. This compensates for the 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'retrieve' and resource 'heart rate history' from macOS HealthKit. It specifies the time window (past N hours) and sorting, distinguishing it from siblings like get_heart_rate (single point) and stream_heart_rate (real-time).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the purpose and parameter constraints (default 24, max 168 hours), implicitly guiding use for historical data. However, it lacks explicit when-to-use vs alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

stream_heart_rateA

Collect heart rate readings from Apple Watch over a time window.

Runs the HealthKit observer for the given duration and returns all samples received, including any buffered readings from the last 5 minutes that hadn't been reported yet.

Note: Apple Watch syncs data through iPhone to Mac via iCloud, so "real-time" updates have network-dependent latency (typically 10-60 s).

Args: duration_seconds: How long to collect readings (1–300 s). Default 30.

Returns: JSON array of heart rate samples, ordered by timestamp.

ParametersJSON Schema
NameRequiredDescriptionDefault
duration_secondsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and effectively discloses behavioral traits: buffering of last 5 minutes, network-dependent latency (10-60 s), and that it runs HealthKit observer. No contradictions; only minor omission of error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured: first sentence states purpose, followed by details, a note on latency, and clear Args/Returns sections. Every sentence is necessary and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one optional parameter, no enums, and an output schema (not shown but mentioned as JSON array), the description covers return format and key behavior. Could mention error handling or prerequisites (e.g., Apple Watch availability) but still above average.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema coverage, the description adds context beyond the schema: duration_seconds has a valid range of 1-300 and a default of 30. This compensates for the schema's lack of description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'collect' and resource 'heart rate readings from Apple Watch', clearly distinguishing from sibling tools 'get_heart_rate' (likely single reading) and 'get_heart_rate_history' (historical data) by focusing on streaming over a time window.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the description implies it's for real-time monitoring with buffered readings and latency explanation, it lacks explicit guidance on when to use this tool versus siblings. Usage context is inferred but not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedget_heart_rate
    • First observedget_heart_rate_history
    • First observedstream_heart_rate
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool serves a distinct purpose: one returns the most recent single reading, one retrieves historical data over a time window, and one streams live data. No overlap.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern using snake_case: get_heart_rate, get_heart_rate_history, stream_heart_rate.

Tool Count5/5

Three tools is appropriate for heart rate access: current reading, history, and streaming. Not too few nor too many.

Completeness4/5

CRUD-like coverage: read single, read history, stream. Minor gap: no way to query a specific time range outside 'past N hours' or duration.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Edplayerone/iwatch-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server