Skip to main content
Glama
madfreakz

google-health-mcp-server

by madfreakz

🩺 google-health-mcp-server

Hand your whole-body health data to your AI — steps, distance, heart rate, and more from Apple Watch, Fitbit, or Pixel Watch, unified through Google Health.

MCP Google Health API v4 License: MIT

An MCP server for the Google Health API v4 — read your daily activity, sleep, heart rate, and body metrics from any source connected to Google Health (Apple Watch import, Fitbit Air, Pixel Watch, ...) in Claude or any MCP client, and optionally sync them into an Obsidian vault.

Self-hosted and local-first: it uses your own Google Cloud OAuth app, tokens are stored on your machine at mode 0600, and no health data leaves your control.

Beta notice. The Google Health API v4 is new (public beta; legacy Fitbit Web API turns down September 2026). Field shapes may still shift. This server normalizes daily values best-effort and always returns the raw rollup points alongside, so nothing is lost if a field mapping in src/constants.ts needs a tweak against live data.

Tools

Tool

What it does

get_daily_summary

Per-day table of steps, distance, active calories, active minutes, resting HR, sleep over a date range (or trailing days). Start here.

list_data_points

Raw, un-rolled-up points for one dataType — intraday HR, sleep stages, or any type not in the summary.

list_paired_devices

Devices paired to the account — confirm a new device (e.g. Fitbit Air) has connected.

connection_status

Health-check: token works? which scopes granted? which metrics actually return data over the last 7 days? Run this first after setup.

sync_health_to_obsidian

Daily markdown notes under {vault}/Lifestyle/Health/ + a rolling 7/30-day dashboard.

Related MCP server: Google Health Fitbit MCP

One-time setup

1. Google Cloud project + API

  1. Create or pick a project at https://console.cloud.google.com/.

  2. Enable the Google Health API: https://console.cloud.google.com/apis/library/health.googleapis.com

  1. Go to APIs & Services → OAuth consent screen. User type External.

  2. Fill in the app name and your email.

  3. Under Audience → Test users, add your own Google account.

  4. On the Data access page, add these scopes (search "Google Health"):

    • …/auth/googlehealth.profile.readonly

    • …/auth/googlehealth.settings.readonly

    • …/auth/googlehealth.activity_and_fitness.readonly

    • …/auth/googlehealth.health_metrics_and_measurements.readonly

    • …/auth/googlehealth.sleep.readonly

    • …/auth/googlehealth.nutrition.readonly

⚠️ 7-day token caveat (and why you should stay in Testing). While the consent screen is in Testing status, Google issues refresh tokens that expire after 7 days. You might expect to fix this by publishing to Production — but the Google Health scopes are Google's Restricted tier, and Restricted scopes in Production require a full security verification (CASA assessment). There is no "click through the unverified warning" bypass for Restricted scopes (that bypass only exists for Sensitive scopes). Verification is impractical for a single-user personal tool, so the recommended setup is: keep the app in Testing, add yourself as a Test user, and accept the 7-day expiry. Re-authorize lazily — only when you actually use the data and a call reports the token has lapsed — by re-running npm run oauth (a ~10s browser approve). Don't bother re-authing in weeks you don't touch the data.

3. OAuth credentials

  1. APIs & Services → Credentials → Create credentials → OAuth client ID.

  2. Application type: Web application.

  3. Under Authorized redirect URIs, add exactly:

    http://localhost:47813/callback

    (Must match GOOGLE_HEALTH_OAUTH_PORT. Change both together if 47813 is taken.)

  4. Copy the Client ID and Client secret.

4. Configure + authorize

npm install
cp .env.example .env          # then paste your client ID + secret into .env
npm run oauth                 # opens a browser; approve access. Tokens saved to
                              # ~/.config/google-health-mcp/tokens.json (mode 0600)
npm run build

Verify it works:

node dist/index.js            # should print "Google Health MCP server running on stdio"

…or call connection_status once registered in your MCP client.

Register in Claude

Add to ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude:

{
  "mcpServers": {
    "google-health": {
      "command": "node",
      "args": ["/Users/<you>/projects/google-health-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_HEALTH_TOKENS_PATH": "/Users/<you>/.config/google-health-mcp/tokens.json",
        "OBSIDIAN_VAULT_PATH": "/Users/<you>/Documents/Obsidian Vault"
      }
    }
  }
}

The runtime reads the client ID/secret back from the tokens file, so they don't need to be in the MCP env block — only the token path and (optionally) the vault path.

Obsidian sync (optional)

Interactive queries via the MCP tools are always live and pull on demand. The Obsidian notes + dashboard only need a periodic refresh, so set OBSIDIAN_VAULT_PATH and either call sync_health_to_obsidian from Claude or run the CLI:

npm run sync                  # incremental sync since last run

For an automated refresh, a launchd template is in launchd/. Copy it to ~/Library/LaunchAgents/, replace __USERNAME__, and launchctl bootstrap gui/$(id -u) <plist>. It runs every 4 days (well under the 7-day refresh-token expiry) and is best-effort: if the token has lapsed it logs a "re-auth needed" note, fires a macOS notification, and exits cleanly (no crash-loop) — re-auth with npm run oauth (~10s browser approve).

The 4-day cadence narrows staleness, it does not prevent expiry. The cron can only refresh the access token; the refresh token's 7-day Testing-mode cap is fixed by Google regardless of how often it runs, and getting a new refresh token requires the one-time interactive browser approval in npm run oauth — that step can't be scripted into a cron. What the cadence change buys you is a couple of chances per week to notice an expiry (via the notification) instead of going silent for up to a month.

Develop

npm run build       # tsc --noCheck → dist/
npm run typecheck   # strict type check (excludes tests)
npm test            # vitest — pure logic (civil-date math, value extraction)
npm run dev         # build + run the server on stdio

See CLAUDE.md for architecture notes and known pitfalls.

Available Tools

5 tools
connection_statusCheck Connection StatusA
Read-only

Health-check the Google Health connection: confirms the OAuth token works, reports granted vs recommended scopes, and probes which metrics actually return data over the last 7 days. Run this first when setting up or after a new device syncs to confirm data is flowing.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description rightly focuses on additional behavioral details: checking token validity, scope alignment, and data return over 7 days. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences cover both technical behavior and usage guidance. No wasted words; information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately describes the return value (token status, scopes, metric availability). Could include more structured output hints, but sufficient for decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters, the instruction allows a baseline of 4. The description adds value by explaining what the tool does without relying on parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('health-check', 'confirms', 'reports', 'probes') and identifies the exact resource ('Google Health connection'). It clearly distinguishes from siblings like get_daily_summary or list_data_points, which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to run this tool: 'first when setting up or after a new device syncs'. It doesn't mention when not to use it, but the context is clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_daily_summaryGet Daily Health SummaryA
Read-only

Daily health metrics (steps, distance, active calories, active-zone minutes, floors, resting heart rate, and avg/max heart rate) across all connected Google Health sources (Apple Watch import, Fitbit Air, Pixel Watch). Returns a per-day table plus the raw points. Use start_date/end_date for an explicit range, or days (default 7) for a trailing window. Pass metrics to pick a subset. This is the primary tool for "how have my steps/HR/calories trended" questions.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoWindow size in days ending today, used only when start_date is omitted. Default 7.
metricsNoSubset of metric keys to include. Available: steps, distance, activeCalories, activeZoneMinutes, floors, restingHeartRate, heartRateAvg, heartRateMax, heartRateMin. Default: steps, distance, activeCalories, activeZoneMinutes, floors, restingHeartRate, heartRateAvg, heartRateMax.
end_dateNoEnd date YYYY-MM-DD (inclusive). Defaults to today.
start_dateNoStart date YYYY-MM-DD (inclusive). Defaults to `days` ago.

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about data aggregation across sources and return format, but does not mention any potential performance or state implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (4-5 sentences), front-loaded with what the tool returns, and efficiently covers parameter usage without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description mentions return structure (per-day table plus raw points) and covers parameter combos. Lacks minor details like output format specifics or constraints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds guidance on parameter relationships (start_date vs. days) and usage examples, which goes beyond raw schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns daily health metrics across all connected sources, and distinguishes itself from siblings like sync_health_to_obsidian by being the primary trend tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly guides when to use start_date/end_date vs. days, how to subset metrics, and positions itself as the primary tool for trend questions, implicitly differentiating from sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_data_pointsList Raw Health Data PointsA
Read-only

Fetch raw (un-rolled-up) data points for a single Google Health dataType — use when you need finer-than-daily granularity (e.g. intraday heart rate samples, individual sleep stages) or a dataType not covered by get_daily_summary. Accepts a friendly key (steps, sleep, heartRate, ...) or a raw API dataType string, plus an optional date range or raw filter. Prefer get_daily_summary for trend/summary questions — it is far cheaper.

ParametersJSON Schema
NameRequiredDescriptionDefault
filterNoRaw API filter string, passed through verbatim. The list filter grammar is not standardized in the v4 beta — omit unless you know it. For date ranges, use get_daily_summary instead.
data_typeYesGoogle Health dataType segment. Common keys map to: steps→steps, distance→distance, activeCalories→active-energy-burned, activeZoneMinutes→active-zone-minutes, floors→floors, restingHeartRate→daily-resting-heart-rate, heartRateAvg→heart-rate, heartRateMax→heart-rate, heartRateMin→heart-rate. You may also pass a raw dataType string the API supports (e.g. heart-rate, sleep, weight, exercise).
max_pagesNoMax pages to fetch. Default 5.
page_sizeNoMax points per page. Default 1000 (lists most recent first).

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds behavioral context beyond annotations: confirms read-only nature, explains pagination defaults (most recent first, max pages/ page size limits), and notes raw filter complexity. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise paragraphs with no redundant sentences. Every sentence adds distinct information: purpose, use cases, parameter behavior, and alternative. Well-structured for quick reading.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all necessary aspects given tool complexity: purpose, parameters, usage guidelines, and behavioral quirks. No output schema exists, so return value details are omitted, but context is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions already cover all 4 parameters with 100% coverage. Description adds value by mapping common keys to raw dataType strings and clarifying the filter parameter's obscurity, enhancing usability.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches raw health data points with finer-than-daily granularity, distinguishing from get_daily_summary by mentioning intraday data and dataType coverage. The verb 'fetch' and specific resource (raw data points for a single Google Health dataType) are precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (finer granularity, unsupported dataTypes) and when to use alternative (get_daily_summary for trends). Provides clear guidance with comparative cost hint ('far cheaper'), aiding selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_paired_devicesList Paired DevicesA
Read-only

List devices paired to the Google Health account (e.g. Apple Watch import source, Fitbit Air, Pixel Watch) with manufacturer/model/type. Useful to confirm a new device has connected.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds context about the returned information (manufacturer/model/type) but does not disclose additional behavioral traits like rate limits or authentication needs, which are not critical given the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that conveys the purpose and a use case without any unnecessary words. It is well-structured and front-loaded with the action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description adequately covers the functionality and a typical use case. It could mention if there are limits on the number of devices returned, but for a simple list tool, it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and schema description coverage is 100%. The description adds value by specifying what information the list includes (manufacturer/model/type) beyond what the schema provides, making it more useful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists devices paired to the Google Health account, with specific examples (Apple Watch, Fitbit Air, Pixel Watch) and details on what information is included (manufacturer/model/type). This is distinct from sibling tools like connection_status or list_data_points.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear use case: 'Useful to confirm a new device has connected.' This informs when to use the tool, though it does not explicitly mention when not to use it or compare with alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sync_health_to_obsidianSync Health to ObsidianA

Export daily health summaries to Obsidian as per-day markdown notes under {vault}/Lifestyle/Health/ (frontmatter: steps, distance_km, calories, active_minutes, resting_hr, sleep_hours for Dataview), and refresh {vault}/Lifestyle/Health-Dashboard.md with rolling 7/30-day aggregates. Runs incrementally from the last sync by default; set full_sync=true to re-render the whole window. Requires OBSIDIAN_VAULT_PATH to be set.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoWindow size for a full sync (days ending today). Default 30. Ignored when start_date is set.
end_dateNoExplicit end date YYYY-MM-DD. Default today.
full_syncNoRe-render the whole window from scratch instead of incrementally from the last sync.
start_dateNoExplicit start date YYYY-MM-DD.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool writes to files (export/refresh), specifies the output paths and frontmatter fields, explains incremental vs full sync behavior, and notes the requirement of OBSIDIAN_VAULT_PATH. This adds significant value beyond the annotations, which only indicate not read-only and not destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the primary action, and efficiently covers the mechanism, optional full sync, and prerequisites. Every sentence provides essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's purpose, behavior, and parameters well. However, it does not mention the return value or behavior on error, which could be useful since no output schema is provided. Overall, it is mostly complete for usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% coverage with descriptions for all 4 parameters. The description adds context by explaining the default behavior of incremental sync and the role of full_sync, and implies the relationship between days and start_date. This adds marginal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool exports daily health summaries to Obsidian as per-day markdown notes and refreshes a dashboard. It uses specific verbs (export, refresh) and resources (per-day notes, dashboard), and distinguishes from sibling tools that focus on data retrieval or connection status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the default incremental behavior and how to trigger a full sync, and mentions the required environment variable. It provides clear context for usage but does not explicitly state when to avoid this tool or compare it to alternatives, though the context from sibling tools makes it distinct.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A4.2/5.0
Disambiguation4/5

Tools are mostly distinct: connection_status is a health-check, get_daily_summary and list_data_points differ by granularity and scope, but get_daily_summary also returns raw points, causing potential overlap. Descriptions help guide selection.

Naming Consistency2/5

Naming is inconsistent: 'connection_status' uses noun_noun while others use verb_noun patterns (get_, list_, sync_). Mixed styles like 'daily_summary' and 'paired_devices' also break pattern.

Tool Count5/5

Five tools are well-scoped for a Google Health MCP server: connection check, daily summary, raw data points, device listing, and Obsidian export. No redundancy or excess.

Completeness4/5

Covers core data retrieval and export, but lacks tools for updating or managing health data, which are less common in this domain. Minor gap in querying specific data types beyond the summary.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    A
    maintenance
    A local-first MCP server that enables AI agents to read user-authorized Google Health API v4 data from Fitbit, Pixel Watch, and partners via OAuth, with tokens never leaving the machine.
    26
    867
    48
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    A personal MCP server on Cloudflare Workers that connects Claude to Google Health API v4, enabling reading of health data like activity, sleep, heart rate, SpOâ‚‚, HRV, and nutrition.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/madfreakz/google-health-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server