Ultrahuman MCP

A compact, read-only Model Context Protocol server for Ultrahuman Partner API health data. It is designed to minimize provider calls and model-context usage while preserving the distinction between measured, derived, and unavailable values.

Health data is sensitive. This project is not medical advice and is not affiliated with Ultrahuman.

Features

• Compact daily, sleep, recovery, activity, CGM, and time-series tools

• Correct handling for the provider's capitalized Sleep metric

• Explicit available / missing status; absent data is never reported as zero

• Units, source fields, sample counts, and derived-value markers

• Per-date cache: 24 hours for completed days; 5 minutes for today

• Concurrent-request de-duplication

• Three-attempt transient-failure retry with backoff

• Trend range limit of 31 days and bounded concurrency of four requests

• Downsampled series by default; maximum 500 returned points

• Read-only: no profile writes, device changes, or credential MCP tools

Related MCP server: mcp-server-whoop

Partner API and authentication

Ultrahuman's documented Partner API uses OAuth 2.0 authorization-code and refresh-token flows, with profile, ring_data, and cgm_data scopes. A production deployment should use OAuth and store the client secret, access token, and rotated refresh token in a protected server-side secret store.

This server's default transport retains compatibility with an existing legacy Partner metrics deployment (/api/v1/metrics with a configured API key and email) because OAuth client credentials are not universally available. Set ULTRAHUMAN_API_BASE_URL when deploying a documented OAuth-compatible adapter. Do not assume legacy and OAuth endpoints have identical schemas.

Credentials

Store credentials outside the repository, with directory mode 700 and file mode 600:

ULTRAHUMAN_API_KEY=provider-issued-secret
ULTRAHUMAN_EMAIL=consented-user-email

Default file:

~/.config/ultrahuman-mcp/credentials.env

Override via ULTRAHUMAN_CREDENTIAL_FILE. Never put credentials in source, MCP arguments, logs, or chat.

Tools

All dates are YYYY-MM-DD. Time filters for series are UTC HH:mm until a provider user-time-zone field is available.

Install and test

npm install
npm test
node src/main.js

Data-quality rules

• A missing source field becomes { "value": null, "status": "missing" }.

• Calculated values identify derived: true and include sample counts.

• A zero is emitted only when the provider actually supplies zero.

• Series responses include original and returned point counts plus a downsampled flag.

• Completed-day results can be cached; current-day data is intentionally short-lived.

Current API coverage

The implementation supports metrics observed from the Partner metrics payload: sleep, HR, HRV, temperature, steps, resting HR, recovery, movement, active time, VO₂ max, glucose, average glucose, glucose variability, HbA1c, time-in-target, and metabolic score. Availability depends on the user's product, consent, and granted scopes.

Security

Use least-privilege scopes. Keep health data out of logs. On OAuth migration, refresh on 401 once, trust the returned expires_in, atomically persist rotated refresh tokens, and revoke tokens when retiring an integration.

License

MIT