Apple Health 接入 opencode 的原生 MCP 設定教學

This walks through the exact config, the two values you type twice, and the tool-scoping glob that keeps 16 health tools out of your coding context until you actually ask for them.

The config

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "health-export": {
      "type": "local",
      "command": ["npx", "-y", "health-export-mcp"],
      "enabled": true,
      "environment": {
        "HEALTH_DATA_DIR": "/Users/you/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents"
      }
    }
  }
}

type and command are required for a local server, and command is an array, not a shell string, so you cannot chain with &&. HEALTH_DATA_DIR points at the folder holding your .health-cache.json. The server reads that local file and makes zero runtime network calls, so nothing leaves the machine.

Scoping the tools

opencode registers each server's tools with the server name as a prefix, so health-export becomes health_export_get_trends, health_export_compare_periods, and so on. That prefix is the handle for globs. If you use opencode for real code work, disable the health tools globally and switch them on for one agent:

"tools": { "health_export_*": false },
"agent": { "health": { "tools": { "health_export_*": true } } }

Verify and query

From the config directory:

$ opencode mcp list
health-export  local  connected  16 tools

If it says disconnected, it is almost always npx missing from the PATH the TUI inherited. Then ask something real, naming the server so intent is unambiguous: "use the health-export server to call get_trends on resting heart rate over 14 days."

On-device vs cloud

The architectures differ in where the computation happens, not how nice the chart looks. In a cloud health AI, the answer is computed on the vendor's servers because that is where the model lives, and an account is usually required to bill a tenant. With a local MCP bridge, the answer is computed on your iPhone for in-app questions and on your own machine for agent queries, the vendor's servers never hold the rows, and there is no account. The MCP surface is open source and read-only, so the same data can feed opencode, Claude, Cursor, or whatever you run next.

Full setup guide, with the pairing option and timeout details: https://www.healthexport.dev/blog/connect-apple-health-to-opencode-mcp