Case study
WHOOP Personal MCP
A provider-neutral, single-user MCP server that gives authorized AI clients read-only access to structured WHOOP wellness and training context.
- ROLE
- Creator2026 — Present
- STACK
- TypeScriptNode.jsExpressSQLiteOAuth / PKCEMCP 2026-07-28DockerGitHub Actions
PROBLEM
Biometric context is sensitive, time-dependent, and often incomplete. Connecting it to an AI client creates a larger trust boundary than a typical API wrapper: authorization, client identity, stale or missing values, and provider disclosure all need explicit behavior.
APPROACH
The difficult part was not fetching biometric data — it was creating a defensible trust boundary for sensitive information. The server combines owner-gated OAuth and consent, encrypted WHOOP tokens, strict redirect, Origin, and Host validation, explicit freshness and missing-data semantics, and a provider-neutral MCP interface without persisting API responses or tool results.
DEEP DIVE
WHOOP Personal MCP is a provider-neutral, single-user, self-hosted Model Context Protocol server. Authorized clients such as Codex, Claude, Grok, and other compatible MCP clients can request structured wellness and training context through one owner-controlled deployment.
The transport natively serves stateless MCP 2026-07-28 Streamable HTTP and retains a stateless POST-only fallback for older protocol revisions. Six core read-only tools are always available, with optional event context registered only when configured. Outputs keep freshness, coverage, dates, and missing values explicit instead of turning absent data into false certainty.
The security work is the core of the project. Owner-gated consent, OAuth with PKCE, CIMD with DCR compatibility, encrypted WHOOP tokens, and exact redirect, Origin, and Host validation constrain who can connect and where data can flow. WHOOP API responses and computed tool results are processed in memory rather than persisted.
Protocol contracts and missing-data behavior are covered by 194 automated tests. GitHub Actions verifies Node 22 and 24, package and Docker smoke tests, dependency review, and CodeQL analysis, making the repository a security and protocol infrastructure project rather than a provider-specific wellness chatbot.
HIGHLIGHTS
Native MCP 2026-07-28 Streamable HTTP with a stateless compatibility fallback for legacy clients
Six focused read-only tools plus optional event context, with explicit freshness, coverage, and missing-data behavior
PKCE, CIMD/DCR support, encrypted tokens, and strict redirect, Origin, and Host validation
194 automated tests, Node 22/24 CI, package and Docker smoke tests, dependency review, and CodeQL analysis