google-health-mcp-server
Retrieves health data from Apple Watch (steps, distance, heart rate, sleep, etc.) unified through Google Health.
Retrieves health data from Fitbit devices (steps, distance, heart rate, sleep, etc.) unified through Google Health.
Provides tools to read daily activity, sleep, heart rate, and body metrics from the Google Health API v4.
Syncs health data into an Obsidian vault as daily markdown notes and a rolling dashboard.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@google-health-mcp-servershow me my daily activity summary for the last 3 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🩺 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.
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.tsneeds a tweak against live data.
Tools
Tool | What it does |
| Per-day table of steps, distance, active calories, active minutes, resting HR, sleep over a date range (or trailing |
| Raw, un-rolled-up points for one dataType — intraday HR, sleep stages, or any type not in the summary. |
| Devices paired to the account — confirm a new device (e.g. Fitbit Air) has connected. |
| Health-check: token works? which scopes granted? which metrics actually return data over the last 7 days? Run this first after setup. |
| Daily markdown notes under |
Related MCP server: Google Health Fitbit MCP
One-time setup
1. Google Cloud project + API
Create or pick a project at https://console.cloud.google.com/.
Enable the Google Health API: https://console.cloud.google.com/apis/library/health.googleapis.com
2. OAuth consent screen
Go to APIs & Services → OAuth consent screen. User type External.
Fill in the app name and your email.
Under Audience → Test users, add your own Google account.
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
APIs & Services → Credentials → Create credentials → OAuth client ID.
Application type: Web application.
Under Authorized redirect URIs, add exactly:
http://localhost:47813/callback(Must match
GOOGLE_HEALTH_OAUTH_PORT. Change both together if 47813 is taken.)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 buildVerify 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 runFor 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 stdioSee CLAUDE.md for architecture notes and known pitfalls.
Available Tools
5 toolsconnection_statusCheck Connection StatusARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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 SummaryARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Window size in days ending today, used only when start_date is omitted. Default 7. | |
| metrics | No | Subset 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_date | No | End date YYYY-MM-DD (inclusive). Defaults to today. | |
| start_date | No | Start date YYYY-MM-DD (inclusive). Defaults to `days` ago. |
TDQS
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.
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.
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.
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.
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.
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 PointsARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Raw 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_type | Yes | Google 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_pages | No | Max pages to fetch. Default 5. | |
| page_size | No | Max points per page. Default 1000 (lists most recent first). |
TDQS
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.
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.
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.
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.
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.
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 DevicesARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Window size for a full sync (days ending today). Default 30. Ignored when start_date is set. | |
| end_date | No | Explicit end date YYYY-MM-DD. Default today. | |
| full_sync | No | Re-render the whole window from scratch instead of incrementally from the last sync. | |
| start_date | No | Explicit start date YYYY-MM-DD. |
TDQS
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.
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.
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.
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.
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.
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
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 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.
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.
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
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
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Private Apple Health metrics and workout detail for ChatGPT, Claude, and any MCP client.
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Related MCP Servers
- AlicenseBqualityAmaintenanceA 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.2686748MIT
- AlicenseAqualityBmaintenanceAn MCP server that locally authenticates with Google Health API v4 and provides read-only access to Fitbit, Pixel Watch, and other health data for AI agents.2910316MIT
- AlicenseNot gradedqualityCmaintenanceA 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
- FlicenseNot gradedqualityBmaintenanceSelf-hosted MCP server that provides read-only access to Google Health API v4, enabling analysis of personal health data via OpenAI Responses API or ChatGPT.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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