vaultbeat-apple-health

Vaultbeat Apple Health MCP サーバー

Apple Health のデータ — 睡眠ステージ、周期、HRV、安静時心拍数、ワークアウト、体重、VO₂ max、食事、リフト、メモ、症状、気分（State of Mind） — を、エンドツーエンド暗号化によって自分のマシンだけが平文を見られる状態で、自分の AI エージェント（Claude Code、Claude Desktop、Codex、Hermes、OpenClaw など、MCP に対応するものなら何でも）が読み書きできます。

Vaultbeat iPhone アプリは HealthKit を読み取り、すべての記録をスマートフォン上で暗号化します。このパッケージは、エージェントが接続するローカルサーバーです。暗号文をダウンロードし、マシン上で復号して、MCP 経由で提供します。

iPhone (HealthKit → Vaultbeat app, encrypts) ──► cloud (ciphertext only) ──► this server (decrypts locally) ──MCP──► your agent

クラウドには、読み取ることのできない暗号文が保存されます。それを開く鍵は、ペアリング時にマシン上で生成され、マシンの外に出ることはありません。

要件

• Vaultbeat iOS アプリ、1.2.3 以降にサインインしていること — App Store
• uv（uvx 用）。サーバーには Python 3.11 以降が必要です。システムの Python が古い場合は、uvx が適切なインタープリターを自動でダウンロードします。
• エージェントからのアクセスには Vaultbeat Pro が必要です。 マシンをペアリングすると、AI インターフェースの 3 日間のトライアルが始まります。その後は、読み取りと書き込みに Pro が必要です。Pro は iOS アプリ（Settings → Membership）で購入できます。アクセス期間が終了してもデータは削除されず、Pro を購入すれば再ペアリングせずにこのマシンで利用を再開できます。

このサーバーが読み取れる履歴の量は、アプリがアップロードするデータによって決まります。Pro では、履歴全体がアップロードされます。トライアルでは、アプリ 1.2.9 以降は履歴全体、1.2.8 以前は過去 7 日間のデータがアップロードされます。どちらも利用していない場合、アプリ 1.2.8 以前では過去 7 日間のデータがアップロードされ、1.2.9 以降では何もアップロードされません。そのため、履歴が短い場合は同期の遅れではなく、通常はプランの制限が原因です。vaultbeat_doctor で原因を見分けられます。

クイックスタート

1. このマシンを iPhone とペアリングします。

uvx vaultbeat-apple-health@latest bind

QR コードが表示され、待機状態になります。Vaultbeat アプリで MCP tab → Connect an AI server（アプリ 1.2.8 以前：Settings → Data & AI）を開いてスキャンします。このコマンドは 5 分間待機します（変更するには --timeout を指定）。スキャン後は、完了までに 10 分あります。

2. MCP クライアントにサーバーを追加します。

Claude Code では、プラグインとして追加します（サーバーと、ペアリング手順を Claude に案内するセットアップガイドが追加されます）。

/plugin marketplace add Fino-wind/vaultbeat-apple-health
/plugin install vaultbeat-apple-health@vaultbeat

続いて /vaultbeat-apple-health:setup を実行します。または、サーバーのみを追加します。

claude mcp add vaultbeat-health -- uvx vaultbeat-apple-health@latest serve --transport stdio

Claude Desktop — claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json）に追加して、再起動します。

{
  "mcpServers": {
    "vaultbeat-health": {
      "command": "uvx",
      "args": ["vaultbeat-apple-health@latest", "serve", "--transport", "stdio"]
    }
  }
}

Claude Desktop はシェルの PATH を引き継ぎません。uvx が見つからないというエラーが表示された場合は、which uvx で確認した絶対パスを "command" に指定してください。

その他の MCP クライアントでは、uvx vaultbeat-apple-health@latest serve --transport stdio を stdio サーバーとして実行します。@latest を付けることが重要です。付けない場合、uvx は最初にキャッシュしたバージョンを使い続けます。

3. 動作を確認します。 エージェントに vaultbeat_doctor を呼び出すよう依頼するか、次を実行します。

uvx vaultbeat-apple-health@latest doctor

設定、秘密鍵、クラウドへの接続、ペアリング、実際の取得・復号の一連の処理を確認し、まだ読み取れるデータがないデータ種別を一覧表示します。ペアリング直後は、スマートフォンが新しいマシン用の履歴をまだ封印しているため、しばらくデータが空の種類がある場合があります。アプリで MCP tab → Re-sync all health data to AI（アプリ 1.2.8 以前：Settings → Data & AI）を実行すると、処理が速くなります。

iPhone なしで試す

uvx vaultbeat-apple-health@latest --demo doctor
uvx vaultbeat-apple-health@latest --demo serve --transport stdio   # wire this into a client

--demo はグローバルフラグです。サブコマンドの前に指定すると、固定の合成データセットを提供します。ペアリング、クラウド、キーは不要です。すべての結果に demo_mode: true が含まれ、[SYNTHETIC DEMO DATA] バナーが付きます。また、log_* 書き込みツールは使用できません。

MCP ツール

29 個のツールがあります。読み取りで返されるのは、ご自身のデータ、つまりこのマシンとペアリングしたアカウントのデータです。パートナーとマークされたツールでは、partner=true を指定すると、パートナーがアプリで共有を選択したデータ（睡眠、水分、体重、およびパートナーが共有を有効にした場合のみ、周期、症状、気分、メモ）も読み取れます。2 人のデータが 1 つの結果に混在することはありません。すべての読み取りツールで fresh=true を指定すると、ローカルキャッシュを使わずに読み取れます。

診断

ツール	機能
vaultbeat_doctor	このインストールを最初から最後まで診断し、データのないデータ種別とその原因として考えられるものを報告して、ペアリング状態を表示します。誰かにデータが見つからないと伝える前に呼び出すツールです。

健康記録

ツール	返される内容
get_sleep_nights パートナー	毎晩の睡眠をコンパクトな 1 行で返します。就寝時刻と起床時刻、睡眠時間、深い睡眠／REM／コア／覚醒、覚醒回数、最長の連続睡眠時間、睡眠中の心拍数と呼吸数、昼寝が含まれます。1 年分を 1 回の呼び出しで取得できます。暦上の期間を指定するには since="YYYY-MM-DD" を使用します。
get_sleep_detail パートナー	1～2 晩の詳細情報を返します。睡眠ステージの区間と、各ステージの心拍数および呼吸数が含まれます。最新の夜、または日付（since／until）で指定した夜を取得できます。
get_menstrual_cycle パートナー	周期のサンプルと次回の月経予測を返します。要配慮データです。
get_symptoms パートナー	Apple Health の症状と、本人が報告した症状のエピソード（種類、重症度、開始と終了、場所、疑われる誘因）を並べて返します。要配慮データです。
get_state_of_mind パートナー	気分を返します。Apple Health の「心の状態」から、各感情の快・不快の度合い（感情価と Apple の 7 つの領域）、Apple の感情語と生活領域、Watch、ヘルスケアアプリ、その他のアプリから記録されたもの、および AI が記録したものを取得します。日ごとの件数と平均も含まれます。デフォルトでは最新の 100 件を返します。過去の記録には since／until で期間を指定できます。要配慮データです。
get_notes パートナー	日ごとの自由記述メモと、記入者を返します。要配慮データです。
get_strength_log	筋力トレーニングのセッションを返します。エクササイズ、セット数 × 回数、セッションごとのボリュームが含まれます。
get_food_log	日ごとの食事と食品を返します。kcal／タンパク質／脂質／炭水化物は任意です。デフォルトでは、記録のある最新の 14 日分を返します（暦上の 2 週間ではありません）。期間を指定するには since／until を使用します。
get_workouts	ワークアウトを返します。種類、時間、カロリー、距離が含まれます。
get_user_profile	性別、年齢、生年月日、身長を返します。Vaultbeat for iOS 1.2.9 以降が必要です。

日々の数値と分析

ツール	返される内容
get_metric パートナー	1 つ、複数、またはすべての系列について、日ごとの値を返します。睡眠時間、睡眠のタイミングとステージ、安静時 HR、HRV、手首の温度、VO₂ max、体重と体組成、水分、歩数、アクティブ／基礎／総エネルギー、運動時間とスタンド時間、距離、マインドフルネスが含まれます。aggregation（avg／sum／min／max／latest）と granularity（day／week／month／weekday）はサーバー側で計算されます。暦上の期間を指定するには since／until を使用します。値が増加中の系列では、今日のデータに不完全のマークが付き、集計から除外されます。
get_intraday	1 日の中のサンプルを返します。HRV の場合、サンプルがある時間ごとに 1 行（granularity="hourly"）、またはサンプルごとに 1 行（"raw"）を返します。1 日あたり約 8～14 行です。limit は行数を指定します。
list_metric_series パートナー	上記および下記のツールで指定できるすべての系列名と、その単位およびデータ量を返します。
get_metric_trend パートナー	最小二乗法による傾き、端点、平均／中央値／最小値／最大値を返します。
compare_metric_periods パートナー	最新の N 日間と、その前の N 日間を比較します。または、名前を指定した 2 つの期間を比較します。
correlate_metric_series パートナー	両方の系列のデータがある日について、2 つの系列間の Pearson r を返します。lag_days は、ある日のデータと、それより後の日のデータを対応付けます。
分析ツールが返すのは数値のみで、スコア、評価、判定は返しません。また、2 つの点から直線を当てはめることはせず、要求を拒否します。

書き込み — このマシンをペアリングしたアカウントにのみ書き込み、ほかの場所には書き込みません。

ツール	機能
log_food_append / log_strength_append / log_note_append	その日の記録に追加します。その日にすでに記録がある可能性を考慮した、安全な既定の方法で、何も削除できません。
log_food_entry / log_strength_entry / log_note	渡された内容でその日の記録全体を置き換え、削除した内容を正確に報告します。
log_weight_entry	体重測定を記録し、その日の体組成データは保持します。
log_symptom	本人が報告した症状を 1 件、後からの読み取りで睡眠、食事、心拍数と照合できる構造化フィールドとして記録します。
update_symptom / delete_symptom	報告された症状を変更（通常は終了時刻）するか、誤って記録した症状を削除します。
log_state_of_mind	Apple Health の State of Mind の語彙（感情価、感情を表す語、生活領域）を使って、本人がどのように感じているかを記録します。本人が「Allow AI to update Apple Health」をオンにしている場合に限り、iPhone がその記録を Apple Health に書き込みます（iOS アプリ 1.3.0 以降）。
delete_state_of_mind	AI が誤って記録した気分を削除します。iPhone も Apple Health に書き込んだ複製を削除します。

log_note と log_note_append では、partner=true を指定すると、パートナーについてのメモを記録できます。メモは自分のアカウントに保存され、パートナーに送信されることはなく、自分自身のメモとは分けて保存されます。

結果の読み取り

• すべての読み取り結果には coverage ブロックが含まれます。 days_covered は、回答の根拠となる日数です。平均や傾向を示す場合は、必ずこの値も併記してください。more_available: true は、より古い記録が存在し、limit によって取得範囲が制限されたことを意味します（どこまで遡れるかは oldest_available に示されます）。これはデータが欠落していることを示すものではありません。
• 結果には上限があります。 約 60 KB を超える結果は送信されません。ツールは result_too_large と、リクエストを絞り込む方法（より小さい limit、since 日付、全系列ではなく 1 つの系列を指定するなど）の提案を返します。get_metric と get_intraday は、行をコンパクトなテーブル（columns + rows）として返します。
• 不明な引数は拒否されます。 スペルミスのあるパラメーターや廃止されたパラメーターはエラーになり、黙って無視されることはありません。

MCP プロンプト

サーバーは prompts/list を通じて、daily_brief、sleep_review、energy_balance、training_block_review、cycle_aware_read、partner_check_in、log_from_conversation、why_is_this_empty の 8 つのプロンプトも提供します。それぞれ、呼び出すツールを指定し、同じ 2 つのルールを含みます。結論を出す前にデータがどの範囲をカバーしているかを伝え、空の結果はゼロとして扱うのではなく、説明すべきもの（原因はいくつか考えられます）として扱ってください。引数はすべて省略可能です。

プライバシーとセキュリティ

• 復号はこのマシン上でのみ行われます。 クラウドに保存されるのは暗号文と、受信者ごとにラップされた鍵です。暗号文を復号する秘密鍵は、ペアリング時にこのマシン上で生成されます。
• ヘルスデータがこのパッケージの外に出るのは MCP 経由のみです。 コマンドラインのサブコマンドは、マシンのペアリング、ペアリング状態の報告、サーバーの起動を行います。ヘルスデータを出力するものはありません。
• センシティブなカテゴリー。 サイクルデータと Apple Health が記録する症状は、iOS アプリでカテゴリーごとに有効にした場合にのみ、このサーバーに届きます。既定ではオフです。メモ、気分（Apple Health および log_state_of_mind による State of Mind）、本人が報告した症状（アプリ内、または log_symptom 経由）は、常に本人のエージェントが読み取れます。共有を有効にしない限り、これらがパートナーのエージェントに届くことはありません。
• いつでもペアリングを解除できます。 アプリの MCP タブから解除できます（アプリ 1.2.8 以前では、Settings → Data & AI）。解除後、そのマシンは新しいデータを復号できません。
• ツールの結果に秘密鍵やサーバートークンが含まれることはありません。

秘密鍵の保存場所

config.json には保存されません。次の順に探します。

1. VAULTBEAT_PRIVATE_KEY 環境変数が設定されている場合は、その値（読み取り専用で、書き戻されません）— シークレットストアから注入する運用者向けです。
2. システムのキーリング — デスクトップでは通常こちらが使われます。
3. ~/.tether/mcp-local/identity.key、モード 0600 — キーリングがないマシンでの自動フォールバックです。

~/.tether/mcp-local/config.json（モード 0600）には、クラウドから発行されたサーバートークンと公開鍵が保存されます。.tether はアプリの旧名称で、既存のインストール環境からキーを見つけられるよう、意図的にこのパスを維持しています。

「最初からやり直す」ために config.json を絶対に削除しないでください。 秘密鍵はここに保存されていないため、削除しても問題のあるキーは消去されません。新しい ID が作成され、古い ID 用にすでに暗号化されたレコードは永久に読み取れなくなります。ペアリングを修復するには、もう一度 bind を実行してください。このマシンをそのまま再ペアリングし、すでにこのマシン用に暗号化されたデータは保持されます。

ヘッドレスサーバー。 キーリングにアクセスできない場合は、identity.key のフォールバックに任せてください。自動的に有効になります。PYTHON_KEYRING_BACKEND を null バックエンドに設定しないでください。書き込みを受け付けても何も保存しないため、アクセスできる可能性のあるキーリングを隠してしまうだけです。D-Bus セッションは存在するものの、このプロセスから見えない場合（エージェントフレームワーク、systemd、cron によってサーバーが起動されたときによくあります）は、DBUS_SESSION_BUS_ADDRESS を明示的に渡してください。まず値を解決し（echo "unix:path=/run/user/$(id -u)/bus"）、クライアントの env ブロックにその値をそのまま記述します。このブロックはシェルではなく JSON です。

テレメトリ

サーバーは利用状況イベントを PostHog（EU）に送信します。送信内容は、呼び出されたツール、成功したかどうか、処理時間の範囲、AI クライアントとパッケージのバージョンで、これらはこのマシンがペアリングされているアカウントに紐付けられます。ツールの引数、結果、健康データは一切送信されません。無効にするには、VAULTBEAT_TELEMETRY=0（または DO_NOT_TRACK=1）を設定してください。詳細：vaultbeat.app/privacy。

トラブルシューティング

まず doctor を実行してください。 uvx vaultbeat-apple-health@latest doctor は、最初に見つかった問題の修正方法を含む [OK] / [FAIL] の一覧を出力します。doctor --json は同じレポートをエージェント向けに出力します。終了コード 0 は正常を意味します。

読み取り結果が一部しかない、または空です。 まず coverage.more_available を確認してください。true の場合、limit に達しています。さらに多くのデータを要求してください。履歴が少ない状態で false の場合は、「Requirements」に記載されているプラン上限か、ペアリングのデータ同期がまだ完了していない可能性があります。vaultbeat_doctor には、データのない種類と、それぞれについて考えられる原因が表示されます。

QR コードが正しく表示されません（文字化けや行の不揃いなど。通常は UTF-8 以外のコードページを使う Windows 環境で発生します）。ペアリングはまだ待機中なので、bind を再実行しないでください。画面上のコードが置き換わってしまいます。代わりに、コードのすぐ上に表示された JSON ペイロードを画像として出力し（qrencode -o pair.png '<payload>'）、スマートフォンに送信して、アプリのスキャナーで写真から読み込むを選択してください。または、新しいターミナルで chcp 65001 を実行するか、bind --no-qr を実行してペイロードをテキストとして表示してください。

アクセスに関するメッセージが表示され、読み取りに失敗します。 トライアルまたは Pro メンバーシップの期限が切れています。データは削除されていません。iOS アプリ（「設定」→「メンバーシップ」）で Pro を購入すると、再ペアリングせずにこのマシンで利用を再開できます。

HTTP トランスポート

サブプロセスを起動するのではなく、ネットワーク経由で接続するクライアント向けです。

vaultbeat-apple-health serve --generate-token            # mint and store a bearer token, print client config
vaultbeat-apple-health serve --transport http            # 127.0.0.1:8000/mcp, bearer token required

トークンは VAULTBEAT_MCP_HTTP_TOKEN（推奨。シェルの履歴に残りません）または保存済みの設定から読み込まれ、クライアントは Authorization: Bearer <token> として送信します。--show-token は保存済みのトークンを表示します。--no-token を指定すると、認証なしでループバックアドレスにサービスを提供します。

ループバックアドレス以外へのバインド（LAN または VPS 向けの --host 0.0.0.0）はフェイルクローズとなり、トークンと --allow-remote の両方が必要です。トークンは暗号化されずに通信経路を流れるため、前段に TLS を配置してください（Caddy、nginx、Cloudflare）。その他のフラグ：SSE 形式の応答には --sse-response、セッションが必要なクライアントには --stateful-http を指定します。

mcp.json の例（VS Code / Cursor 形式）：

{
  "servers": {
    "vaultbeat-health": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

stdio のみをサポートするクライアントは、mcp-remote を介して HTTP サーバーに接続できます：npx -y mcp-remote http://127.0.0.1:8000/mcp --header "Authorization: Bearer <token>"。

問題の報告

このリポジトリでは、MCP サーバーと Vaultbeat iPhone アプリの両方に関する問題を受け付けています — インストールの失敗、ツールのエラー、バインドが完了しない問題、doctor が問題を報告する場合や、アプリの問題（UI、サブスクリプション、HealthKit の権限プロンプト、同期内容がスマートフォンに表示されないなど）も対象です。 問題を報告 し、該当するテンプレートを選択してください。質問やアイデアは ディスカッションに投稿できます。

このリポジトリは公開されています。健康データ、ペアリングコード、アカウント情報は絶対に貼り付けないでください。

開発

コマンドラインには6つのサブコマンドがあり、いずれも健康データを読み取りません。

vaultbeat-apple-health bind      # pair this machine with the iOS app (QR)
vaultbeat-apple-health status    # local pairing state
vaultbeat-apple-health doctor    # self-diagnosis
vaultbeat-apple-health init      # generate a keypair and config without pairing
vaultbeat-apple-health poll      # poll once for a pending pairing
vaultbeat-apple-health serve     # run the MCP server (stdio or http)

復号されたレコードは、データタイプごとに ~/.tether/mcp-local/cache/ に600秒間キャッシュされます（ファイルは 0600、ディレクトリは 0700）。VAULTBEAT_MCP_CACHE_TTL で期間を上書きできます（0 を指定すると無効になります）。最初の読み取り後の更新では、変更されたレコードのみをダウンロードします。別のサーバー ID とペアリングすると、キャッシュはクリアされます。

クローンからチェックを実行します：

uv sync --frozen --all-extras
uv run --frozen pytest -q tests
uv run --frozen ruff check src tests
uv run --frozen mypy src

vaultbeat-mcp と vaultbeat-mcp-local は、パッケージ名が vaultbeat-apple-health に変更される前のインストール（0.6.2）向けに、引き続きコンソールスクリプトのエイリアスとして残されています。