Configure your agent

The Mac app contains two signed helpers. healthmd-mcp gives agents typed tools. healthmd gives you CLI commands.

The separate portable CLI can connect directly to a phone. This feature is a preview and has not completed stable release tests.

HealthKit stays on iPhone.

A local client can use only the Health.md interfaces that you configure. The client cannot read HealthKit directly. Health.md does not upload your source library.

Choose an interface

Goal	Start with	Continue to
Let Codex or Claude query and chart health data on Mac	Bundled healthmd-mcp over stdio	MCP server & tools
Export canonical JSON or generated files in a Mac script	Bundled healthmd CLI	CLI
Connect directly to an open iPhone or Android phone without the Mac app	Portable direct CLI (preview)	Direct phone access
Build against exact request and response envelopes	Loopback API or public contracts	Loopback API
Parse schemas, records, evidence, or generated fixtures	Versioned reference	Data contracts

Health.md does not change from direct phone access to the Mac app without your action.

Codex with the Mac app

Available now · signed Mac helper

Install Health.md for Mac. Open its CLI screen. If the app is not in /Applications, copy the displayed MCP path.

Add the signed healthmd-mcp helper to ~/.codex/config.toml:

[mcp_servers.healthmd]
command = "/Applications/Health.md.app/Contents/Helpers/healthmd-mcp"
args = []
startup_timeout_sec = 10
tool_timeout_sec = 1200
default_tools_approval_mode = "prompt"

Restart Codex. Call healthmd_doctor to check setup. Use healthmd_metrics to find metric IDs.

Use the refresh tool to get a small data scope. Then query that scope with a typed tool such as healthmd_metric_chart.

The bundled server has 21 tools for setup, refresh jobs, evidence, queries, and visualizations.

Claude Desktop or Claude Code on Mac

Add the bundled helper to Claude Desktop’s MCP configuration or to a trusted Claude Code .mcp.json:

{
  "mcpServers": {
    "healthmd": {
      "command": "/Applications/Health.md.app/Contents/Helpers/healthmd-mcp",
      "args": []
    }
  }
}

Restart the client after you change its configuration. A project configuration requires workspace trust and server approval.

Keep the Mac and iPhone apps open when a tool requests new HealthKit data.

Any stdio MCP client on Mac

Configure one local process:

command: /Applications/Health.md.app/Contents/Helpers/healthmd-mcp
arguments: none
transport: stdio

The host controls stdin and the process. Do not start the helper as an interactive command.

Do not use a shell wrapper that changes JSON-RPC output. Use MCP tools/list to get the schemas from the installed app.

Portable direct setup

Public preview · not yet qualified stable

The portable Rust CLI is a public preview. It includes healthmd setup codex, healthmd mcp serve, and direct pairing on Linux and Windows.

On macOS or Linux, run brew install CodyBontecou/tap/healthmd. Then run healthmd setup codex to configure Codex and pair an iPhone.

You can run the setup command again without making duplicate configuration entries.

Use the mobile build that the release evidence names. A published package does not prove mobile compatibility.

Read Direct phone access for transport and protocol details.

Explicit CLI workflows

Use healthmd directly for canonical extraction or file automation:

healthmd status
healthmd extract --category Sleep --last 7 --output sleep.json
healthmd export --last 7 --destination "$HOME/Documents/HealthVault"

The bundled Mac helper and portable CLI have different commands and release status. Read Health.md CLI before you automate a command.

Portable pairing and readiness

Preview · portable direct workflows

These portable workflows are a preview. The bundled Mac MCP helper uses the Mac app's existing iPhone connection.

Direct MCP and CLI workflows require one trusted pairing with Health.md on iPhone. Pairing uses authenticated encryption and the operating system credential store.

1. Enable Direct CLI Access in Health.md on iPhone.
2. Start pairing from healthmd setup codex or healthmd direct pair.
3. Approve the bounded pairing request on iPhone.
4. Keep Health.md in the foreground when you start a query or export.
5. Before a large request, call healthmd_doctor in MCP. In the portable CLI, run healthmd status.

Read Direct phone access for Manual IP, Tailscale, ports, trusted devices, foreground use, and recovery.

Configuration boundaries

A local agent configuration does not grant:

• Unrestricted HealthKit access
• Unrestricted file access
• Unrestricted URLs, shell commands, prompts, roots, or MCP sampling
• Permission to hide missing data, coverage, units, evidence, or limits
• Permission to resume, cancel, or overwrite files without the required approval.

For a complete result, inspect the requested scope, coverage, traversal, limits, and source schema. Process success is not sufficient evidence.

Continue

Tool interfaceReview tools, MCP Apps, schemas, paging, exports, and sandbox limits. First questionsRun typed metric, sleep, workout, comparison, coverage, and evidence queries. Canonical dataExtract schema-v8 documents and source records without putting large data in chat. ContractsBrowse versioned structures, field lists, fixtures, and integration examples.