# Healthmirror Mcp

> Local MCP server that exposes your Apple Health data (synced to your Mac by the HealthMirror iOS app) to AI tools like Claude — runs locally, no network access.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mlyxz-healthmirror-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mlyxz](https://agentstack.voostack.com/s/mlyxz)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mlyxz](https://github.com/mlyxz)
- **Source:** https://github.com/mlyxz/healthmirror-mcp
- **Website:** https://apps.apple.com/app/id6779814305

## Install

```sh
agentstack add mcp-mlyxz-healthmirror-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# HealthMirror MCP

**English** · [简体中文](./README.zh.md)

A local [MCP](https://modelcontextprotocol.io) server that exposes your own Apple
Health data — exported to iCloud Drive by the **HealthMirror** iOS app — to AI
tools running on your Mac (e.g. Claude).

It reads the JSONL files HealthMirror writes into its iCloud container and answers
structured queries (sleep, heart-rate metrics, workouts, a daily recovery summary).
Your health data never leaves your machine: the server runs locally, has no network
access, and only returns query results to the MCP client you connect.

- **iOS app:** [HealthMirror: Auto Sync on the App Store](https://apps.apple.com/app/id6779814305)
- **Privacy Policy:** [English](./PRIVACY.md) · [简体中文](./PRIVACY.zh.md)
- **Support:** [English](./SUPPORT.md) · [简体中文](./SUPPORT.zh.md)

## How it works

```
iPhone HealthKit
  ↓  HealthMirror iOS app   (reads HealthKit, writes JSONL)
iCloud Drive container:  iCloud.com.mlyz.HealthBridge
  ↓  macOS iCloud auto-sync
~/Library/Mobile Documents/iCloud~com~mlyz~HealthBridge/Documents/
  ↓  this MCP server        (reads JSONL, runs queries)
Claude / any MCP client
```

The server is read-only over your data and makes no outbound network requests
(enforced by a sandbox profile — see [Security model](#security-model)).

## Requirements

- macOS (Apple Silicon or Intel).
- The [**HealthMirror**](https://apps.apple.com/app/id6779814305) iOS app installed on
  your iPhone with iCloud sync enabled, so health data has synced down to this Mac.
  Without the app there is no data to read.
- [uv](https://docs.astral.sh/uv/) — `brew install uv`.
- Python ≥ 3.12 (uv can install this for you).

## Install

```bash
git clone https://github.com/mlyxz/healthmirror-mcp.git
cd healthmirror-mcp
uv sync
```

Confirm your health data has actually synced to this Mac — this folder should exist
and contain per-metric subfolders:

```bash
ls ~/Library/Mobile\ Documents/iCloud~com~mlyz~HealthBridge/Documents/raw/
```

If it's missing or empty, open the HealthMirror app on your iPhone, let it finish
syncing, and make sure iCloud Drive is enabled on this Mac.

### Smoke test (no sandbox)

Confirm dependencies resolve and the server starts:

```bash
uv run health-bridge-mcp
```

It speaks the MCP protocol over stdio and waits for a client, so you'll see no
visible output. If it starts without an import error, you're good — press Ctrl+C
to exit.

## Register with Claude (recommended: sandboxed)

The repo ships `run-sandboxed.sh`, which launches the server inside a macOS
`sandbox-exec` profile that **denies all network access** and restricts writes to a
small allow-list. This is the recommended way to run it.

```bash
claude mcp add healthmirror /ABSOLUTE/PATH/TO/healthmirror-mcp/run-sandboxed.sh
```

Replace `/ABSOLUTE/PATH/TO/healthmirror-mcp` with the real path where you cloned the
repo. The wrapper resolves your home directory and the repo location automatically,
so you never have to edit absolute paths inside `sandbox.sb`.

To run **without** the sandbox (e.g. while debugging), register the plain command:

```bash
claude mcp add healthmirror -- uv run --directory /ABSOLUTE/PATH/TO/healthmirror-mcp health-bridge-mcp
```

Other MCP clients: launch `run-sandboxed.sh` as the server command; it communicates
over stdio.

> **`uv: command not found`?** GUI-launched MCP clients sometimes don't inherit your
> shell `PATH`. `run-sandboxed.sh` tries common install locations automatically; if it
> still fails, run `which uv` and use that full path. For **Claude Desktop**, point its
> MCP config JSON at `"command": "/ABSOLUTE/PATH/TO/healthmirror-mcp/run-sandboxed.sh"`.

## Tools

| Tool | What it does |
|---|---|
| `ping` | Liveness / connection check. |
| `get_sleep` | Sleep episodes (main sleep + naps), per-stage minutes, coverage. |
| `get_metric` | A quantity metric (`heart_rate`, `hrv_sdnn`, `resting_heart_rate`, `active_energy`, `steps`, `weight`) with aggregation, optional per-day buckets, and per-source breakdown. |
| `get_workouts` | Workout records with multi-source dedup, plus a per-type summary. |
| `get_daily_summary` | One-shot daily summary: recovery score, cycle phase, today's activity, last night's sleep. |

By default queries are limited to the last 30 days; pass `allow_historical=true` for
older data. Every tool call is appended as a line to
`~/Library/Application Support/HealthBridge/audit.log`, so you can see what the AI
queried (`tail -f` it). See [Security model](#security-model) for exactly what that
log records.

## Security model

- **No network.** The sandbox profile denies all network access; the server cannot
  exfiltrate data. This is the primary protection.
- **Writes are allow-listed.** Only the HealthMirror app-support directory, the cloned
  repo's own venv/bytecode cache, and Python temp are writable.
- **Reads are not sandbox-restricted** (macOS needs broad read access to load), but the
  server code only reads your local HealthMirror data — and with the network blocked, a
  read can't go anywhere.
- **Audit log.** Each call appends tool name, params, and a small result summary to a
  local log — result counts and a few derived figures (e.g. the daily recovery score),
  never the raw health samples.

`sandbox-exec` is marked deprecated by Apple but remains functional on current macOS.

## Why two names?

The product and this repository are named **HealthMirror**. The Python package and
module keep the original development codename **`health_bridge`** (distribution
`health-bridge-mcp`, import `health_bridge_mcp`), and the iCloud container ID is
`iCloud.com.mlyz.HealthBridge`. These identifiers were frozen early to avoid
disrupting a working data pipeline, so they intentionally differ from the product
name. Functionally it's all the same project.

## Maintainer

Developed by Xiao Zhang, publishing as [@mlyxz](https://github.com/mlyxz) on GitHub.
Contact: support@mlyz.me

## License

[MIT](./LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mlyxz](https://github.com/mlyxz)
- **Source:** [mlyxz/healthmirror-mcp](https://github.com/mlyxz/healthmirror-mcp)
- **License:** MIT
- **Homepage:** https://apps.apple.com/app/id6779814305

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mlyxz-healthmirror-mcp
- Seller: https://agentstack.voostack.com/s/mlyxz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.