Apple Health in Gemini CLI

What you need

• An iPhone on iOS 15 or later with Apple Health. Apple Watch data comes along too.
• The HealthAPI app. Free for 2 days, no card needed. Then an optional 7-day free trial when you subscribe. The preview includes 25 requests a day. When the 2 days are up, AI apps and the API stop reading your data until you choose a plan in the app. Your synced data is kept for about 5 weeks, so subscribing picks up where you left off. Pro is $4.99 a month or $49.99 a year (100 requests a day); Developer is $9.99 a month or $99.99 a year (1,000 a day). Cancel anytime in the App Store.
• Gemini CLI on a computer with a web browser.

Set it up in 4 steps

1. 1

   Install HealthAPI and sync

   Get HealthAPI from the App Store, open it and allow Apple Health. Your history uploads, then new data keeps syncing.
2. 2

   Add the server

   Run gemini mcp add --scope user --transport http healthapi https://healthapi.app/mcp. The user scope puts it in ~/.gemini/settings.json, so it works in every folder.
3. 3

   Sign in and approve on your iPhone

   Start gemini and run /mcp auth healthapi. A HealthAPI page opens in your browser with a short code. Scan its QR code with your iPhone, or enter the code in HealthAPI under Connect, check it matches, and tap Approve.
4. 4

   Ask Gemini

   Ask for something that needs your data, such as “Use HealthAPI to compare my steps this week with last week.” Gemini asks before each tool call; choose Always allow this server to stop the prompts.

gemini mcp add --scope user --transport http healthapi https://healthapi.app/mcp

Keep --scope user: without it, gemini mcp add writes to the current project's .gemini/settings.json, and in your home folder it refuses. The sign-in page labels the request an unverified app called Gemini CLI MCP Client that returns to a program on this computer. That is expected; approve it if you started it and the codes match. Gemini CLI waits 5 minutes for the approval; if it gives up, run /mcp auth healthapi again for a new code.

Run /mcp list in Gemini CLI, or gemini mcp list in a terminal, to check the server is connected. Gemini knows the tools as mcp_healthapi_get_sleep, mcp_healthapi_get_trend and so on, and it reads HealthAPI's own instructions too: dates are in your timezone, and a night of sleep belongs to the morning it ended.

The settings.json entry

The command writes the entry for you. To write it by hand, Google's documentation uses httpUrl for a streamable HTTP server:

{
  "mcpServers": {
    "healthapi": {
      "httpUrl": "https://healthapi.app/mcp"
    }
  }
}

Gemini CLI keeps the sign-in in ~/.gemini/mcp-oauth-tokens.json and refreshes it on its own. It asks before every tool call unless you allow the server; HealthAPI's tools only read, but each call uses one of your daily requests.

With an API key instead

For a machine without a browser, send your API key as a header. Copy it in the app (Connect, then Other tools). The key is written into the file as is, so keep it in your user settings, never a project's .gemini/settings.json:

{
  "mcpServers": {
    "healthapi": {
      "httpUrl": "https://healthapi.app/mcp",
      "headers": { "Authorization": "Bearer <your API key>" }
    }
  }
}

What to do with it

• Ask about a trend. “Use HealthAPI to get 90 days of HRV and resting heart rate. Are they moving together, and on which days did they split?”
• Turn it into files. “Get my last 8 weekly summaries and write them to weeks.csv, one row per week.”
• Write a script around it. “Look at one daily summary from HealthAPI, then write a Python script that pulls the same fields from the REST API each morning.”
• A training log. “List my workouts since the start of the month with time, distance and energy, and total them by type.”

Scripts that run on their own should call the REST API with your key; see the Python and JavaScript guides. All eight tools and their inputs are on the MCP server page.

Questions