How do I use ultrahuman_mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ultrahuman_mcp Show my sleep analysis for last night" 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.

ultrahuman_mcp

by crixalis17

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

💍 Ultrahuman Ring MCP Server

A Model Context Protocol (MCP) server that exposes real-time health data from the Ultrahuman Ring to AI agents, LLMs, and agentic workflows. The server connects to the Ultrahuman Partner API, processes raw biometric data, and returns agent-optimized summaries with trend analysis, quality classifications, and actionable insights.

Related MCP server: Ultrahuman MCP Server

Architecture Overview

┌─────────────────────┐       stdio        ┌──────────────────────────┐       HTTPS        ┌──────────────────────┐
│   LLM / AI Agent    │◄──────────────────►│  Ultrahuman MCP Server   │◄──────────────────►│  Ultrahuman API      │
│  (Claude, GPT, etc) │   MCP Protocol     │  (Node.js / TypeScript)  │   Partner API v1   │  partner.ultrahuman  │
└─────────────────────┘                    └──────────────────────────┘                    └──────────────────────┘
                                                     │
                                                     ▼
                                           ┌──────────────────────┐
                                           │  Smart Summarization │
                                           │  • Time filtering    │
                                           │  • Trend analysis    │
                                           │  • Quality scoring   │
                                           │  • Insight generation│
                                           └──────────────────────┘

The server sits between the LLM agent and the raw Ultrahuman API. It performs:

Authentication — Injects the API key on every request.
Smart Summarization — Converts raw time-series arrays into aggregated stats (avg, min, max, trend, count).
Time Filtering — Supports last_minutes, start_time/end_time windows, and date selection.
Quality Classification — Maps numeric scores to human-readable labels (excellent, good, fair, poor).
Insight Generation — Produces contextual health insights from cross-metric analysis.

Prerequisites

Requirement	Details
Node.js	v18 or higher
Ultrahuman Ring	With active subscription and data synced
API Key	Obtain from Ultrahuman Vision

Quick Start

1. Install Dependencies

npm install

2. Configure API Key

cp .env.example .env

Edit .env:

ULTRAHUMAN_API_KEY=your_api_key_here

3. Build & Start

npm run build
npm start

The server communicates over stdio (standard input/output) using the MCP protocol.

MCP Client Configuration

Claude Desktop

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

{
  "mcpServers": {
    "ultrahuman": {
      "command": "node",
      "args": ["/absolute/path/to/ultrahuman_mcp/dist/index.js"],
      "env": {
        "ULTRAHUMAN_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor / Windsurf / Other MCP Clients

Configure with:

Command: node
Args: ["/absolute/path/to/ultrahuman_mcp/dist/index.js"]
Environment: ULTRAHUMAN_API_KEY=your_key
Transport: stdio

Common Parameters

Most tools accept the following optional filter parameters:

Parameter	Type	Format	Description
`date`	`string`	`YYYY-MM-DD`	Target date. Defaults to today if omitted.
`last_minutes`	`number`	integer	Restrict data to the last N minutes from now. Example: `30` returns data from the last 30 minutes.
`start_time`	`string`	`HH:MM` (24h)	Start of a time window on the given date. Example: `"09:00"`
`end_time`	`string`	`HH:MM` (24h)	End of a time window on the given date. Example: `"17:00"`
`format`	`string`	`"summary"` \| `"detailed"`	`"summary"` (default) returns aggregated statistics. `"detailed"` returns raw time-series arrays.

Note: last_minutes takes precedence over start_time/end_time. If neither is specified, the full day's data is used. The format parameter is only supported by get_heart_vitals.

Time Filtering Behavior

last_minutes=30 — Computes an epoch range from (now - 30min) to now and filters all time-series readings.
start_time="09:00" + end_time="17:00" — Filters readings to the 9 AM – 5 PM window on the specified date.
No time filter — Returns the complete day's data.
Empty result in time range — If no readings fall in the requested window, the summary will include a message field explaining when the latest available reading was, along with latest_available (ISO timestamp) and minutes_since_last_reading.

Tools Reference

1. `get_health_summary`

Best starting tool. Use this first to get a high-level overview of the user's health before drilling into specifics.

Returns a comprehensive health overview combining sleep, recovery, activity, vitals, and AI-generated insights.

Input Schema

{
  "date": "2025-01-27",          // optional, defaults to today
  "last_minutes": 60,            // optional
  "start_time": "06:00",        // optional
  "end_time": "22:00"           // optional
}

All parameters are optional. Calling with {} returns today's full summary.

Response Schema

{
  "date": "2025-01-27",
  "time_range": {                         // null if no time filter applied
    "start": "2025-01-27T06:00:00.000Z",
    "end": "2025-01-27T22:00:00.000Z"
  },
  "scores": {
    "sleep": 82,                          // 0–100, null if unavailable
    "recovery": 75,                       // 0–100, null if unavailable
    "activity": 6.5                       // movement index, null if unavailable
  },
  "vitals": {
    "resting_hr": 58,                     // BPM, null if unavailable
    "avg_hrv": 45,                        // ms, null if unavailable
    "avg_spo2": 97.2,                     // %, null if unavailable
    "body_temp": 36.5                     // °C, null if unavailable
  },
  "activity": {
    "total_steps": 8432,
    "active_minutes": 45,                 // null if unavailable
    "vo2_max": 42.3                       // ml/kg/min, null if unavailable
  },
  "sleep": {
    "total_hours": 7.2,                   // null if unavailable
    "efficiency": 88,                     // %, null if unavailable
    "quality": "good"                     // "excellent" | "good" | "fair" | "poor"
  },
  "insights": [
    "Excellent sleep quality last night",
    "Body is well recovered and ready for activity",
    "Great job! Step goal achieved"
  ]
}

Insight Generation Rules

Condition	Insight
Sleep score ≥ 80	"Excellent sleep quality last night"
Sleep score < 60	"Sleep quality could be improved"
Recovery score ≥ 80	"Body is well recovered and ready for activity"
Recovery score < 50	"Consider lighter activity today for recovery"
Steps ≥ 10,000	"Great job! Step goal achieved"
Steps < 3,000	"Consider increasing movement today"
Heart rate trend = rising	"Heart rate trending upward"

2. `get_heart_vitals`

Returns heart rate, HRV (heart rate variability), and SpO2 (blood oxygen) metrics. Supports both summary and detailed output formats.

Input Schema

{
  "date": "2025-01-27",          // optional
  "last_minutes": 30,            // optional
  "start_time": "09:00",        // optional
  "end_time": "17:00",          // optional
  "format": "summary"           // optional: "summary" (default) | "detailed"
}

Response Schema — Summary (default)

{
  "heart_rate": {
    "count": 482,
    "avg": 72.3,
    "min": 54,
    "max": 132,
    "latest": 68,
    "trend": "stable",              // "rising" | "falling" | "stable"
    "time_range": {
      "start": "2025-01-27T00:05:00.000Z",
      "end": "2025-01-27T23:55:00.000Z"
    },
    "resting_hr": 56                // from night/sleep RHR, null if unavailable
  },
  "hrv": {
    "count": 240,
    "avg": 42.8,
    "min": 18,
    "max": 89,
    "latest": 45,
    "trend": "rising",
    "time_range": { "start": "...", "end": "..." },
    "avg_sleep_hrv": 52             // null if unavailable
  },
  "spo2": {
    "count": 120,
    "avg": 97.1,
    "min": 94,
    "max": 99,
    "latest": 97,
    "trend": "stable",
    "time_range": { "start": "...", "end": "..." }
  }
}

Response Schema — Detailed (`format: "detailed"`)

{
  "hr": [
    { "value": 72, "timestamp": 1706313600 },
    { "value": 68, "timestamp": 1706313900 }
  ],
  "hrv": [
    { "value": 45, "timestamp": 1706313600 }
  ],
  "spo2": [
    { "value": 97, "timestamp": 1706313600 }
  ],
  "night_rhr": 56,
  "sleep_rhr": 54,
  "avg_sleep_hrv": 52
}

Trend Calculation

Trend is determined by comparing the average of the first third of readings to the average of the last third:

Rising: Last third avg is >5% higher than first third avg
Falling: Last third avg is >5% lower than first third avg
Stable: Within ±5%

3. `get_sleep_analysis`

Returns comprehensive sleep metrics for a given night. Sleep data is a nightly aggregate — time filters (last_minutes, start_time, end_time) are not applicable.

Input Schema

{
  "date": "2025-01-27"           // optional, defaults to today
}

Response Schema

{
  "sleep_score": 82,                       // 0–100, null if no data
  "total_sleep_hours": 7.2,               // decimal hours, null if no data
  "sleep_efficiency_percent": 88,          // %, null if no data
  "time_in_bed_hours": 8.1,              // decimal hours, null if no data
  "rem_sleep_hours": 1.8,                // decimal hours, null if no data
  "deep_sleep_hours": 1.5,               // decimal hours, null if no data
  "light_sleep_hours": 3.9,             // decimal hours, null if no data
  "restorative_sleep_percent": 42,        // %, null if no data
  "full_sleep_cycles": 4,                // integer count, null if no data
  "tosses_and_turns": 12,                // integer count, null if no data
  "morning_alertness_minutes": 15,        // minutes, null if no data
  "quality": "good"                       // "excellent" | "good" | "fair" | "poor"
}

Quality Classification

Sleep Score	Quality
≥ 85	`"excellent"`
70 – 84	`"good"`
50 – 69	`"fair"`
< 50	`"poor"`

4. `get_activity_data`

Returns activity and movement metrics including step counts, active minutes, and fitness indicators.

Input Schema

{
  "date": "2025-01-27",          // optional
  "last_minutes": 60,            // optional
  "start_time": "06:00",        // optional
  "end_time": "22:00"           // optional
}

Response Schema

{
  "total_steps": 8432,
  "steps_trend": {                           // TimeSeriesSummary of step readings
    "count": 96,
    "avg": 87.8,
    "min": 0,
    "max": 520,
    "latest": 42,
    "trend": "falling",
    "time_range": { "start": "...", "end": "..." }
  },
  "active_minutes": 45,                     // null if unavailable
  "movement_index": 6.5,                    // null if unavailable
  "vo2_max": 42.3,                          // ml/kg/min, null if unavailable
  "activity_level": "active"                // classification (see table below)
}

Activity Level Classification

Total Steps	Level
≥ 12,000	`"very_active"`
8,000 – 11,999	`"active"`
5,000 – 7,999	`"moderate"`
< 5,000	`"sedentary"`

Note: When a time filter is applied, total_steps represents the sum of steps within that window only. Activity level classification still applies to the filtered total.

5. `get_recovery_score`

Returns recovery status indicating the body's readiness for physical activity. Recovery data is a daily aggregate — time filters are not applicable.

Input Schema

{
  "date": "2025-01-27"           // optional, defaults to today
}

Response Schema

{
  "recovery_score": 75,                    // 0–100, null if no data
  "recovery_index": 75,                   // same as recovery_score
  "status": "good"                         // "excellent" | "good" | "fair" | "poor"
}

Recovery Status Classification

Recovery Score	Status
≥ 80	`"excellent"`
60 – 79	`"good"`
40 – 59	`"fair"`
< 40	`"poor"`

6. `get_temperature_data`

Returns body temperature metrics including skin temperature readings, baseline deviation, and average body temperature. Useful for detecting illness, stress, or menstrual cycle patterns.

Input Schema

{
  "date": "2025-01-27",          // optional
  "last_minutes": 60,            // optional
  "start_time": "22:00",        // optional
  "end_time": "06:00"           // optional
}

Response Schema

{
  "readings": {                             // TimeSeriesSummary of temperature readings
    "count": 240,
    "avg": 33.2,                            // °C (skin temperature)
    "min": 31.8,
    "max": 34.5,
    "latest": 33.0,
    "trend": "stable",
    "time_range": { "start": "...", "end": "..." }
  },
  "temperature_deviation": 0.3,            // °C deviation from baseline, null if unavailable
  "average_body_temperature": 36.5          // °C, null if unavailable
}

7. `get_daily_metrics`

Raw data tool. Returns the complete, unprocessed API response from the Ultrahuman Partner API. Use this only when you need access to metric types not covered by the other tools, or when you need the original API structure.

Input Schema

{
  "date": "2025-01-27",          // optional, defaults to today
  "start_date": "2025-01-20",   // optional, for date range queries
  "end_date": "2025-01-27"      // optional, for date range queries
}

Note: Use either date (single day) OR start_date + end_date (range). If none are provided, defaults to today.

Response Schema

Returns the raw Ultrahuman API response:

{
  "status": "success",
  "error": null,
  "data": {
    "metrics": {
      "2025-01-27": [
        {
          "type": "hr",
          "object": {
            "values": [
              { "value": 72, "timestamp": 1706313600 }
            ]
          }
        },
        {
          "type": "hrv",
          "object": { "..." }
        },
        {
          "type": "sleep",
          "object": { "..." }
        }
      ]
    }
  }
}

Known metric types in the raw response: hr, hrv, spo2, night_rhr, sleep_rhr, avg_sleep_hrv, sleep, steps, movement_index, active_minutes, vo2_max, recovery_index, temp.

Tool Selection Guide

Use this decision tree to pick the right tool:

User Intent	Recommended Tool
"How am I doing today?" / general health check	`get_health_summary`
"What's my heart rate?" / "How's my HRV?" / "Check my SpO2"	`get_heart_vitals`
"How did I sleep?" / "Sleep quality?"	`get_sleep_analysis`
"How many steps?" / "Am I active enough?"	`get_activity_data`
"Am I recovered?" / "Ready for a workout?"	`get_recovery_score`
"What's my body temperature?" / "Am I running a fever?"	`get_temperature_data`
Need raw/unprocessed data or unsupported metric types	`get_daily_metrics`

Recommended Agent Workflow

Start with get_health_summary to get the big picture.
Drill into specific tools based on what the user asks about or what the insights suggest.
Use time filters (last_minutes, start_time/end_time) to narrow down to relevant windows.
Use format: "detailed" on get_heart_vitals only when the user wants to see individual readings or plot data.
Fall back to get_daily_metrics only when none of the specialized tools cover the requested data.

Response Conventions

TimeSeriesSummary Object

Many tools return a TimeSeriesSummary object for time-series metrics. Its shape is:

{
  "count": 482,                // number of data points
  "avg": 72.3,                 // arithmetic mean
  "min": 54,                   // minimum value
  "max": 132,                  // maximum value
  "latest": 68,                // most recent reading, null if no data
  "trend": "stable",           // "rising" | "falling" | "stable"
  "time_range": {
    "start": "ISO-8601",       // timestamp of earliest reading
    "end": "ISO-8601"          // timestamp of latest reading
  },
  // Only present when no data in requested time range:
  "message": "No data in requested time range. Latest reading was 45 minutes ago.",
  "latest_available": "ISO-8601",
  "minutes_since_last_reading": 45
}

Null Values

All metric fields may return null when:

The ring wasn't worn during the relevant period
Data hasn't synced yet
The metric isn't available for this day

Error Responses

On failure, tools return:

{
  "error": "Description of what went wrong"
}

Common errors:

"API request failed: 401 Unauthorized" — Invalid or expired API key
"API request failed: 429 Too Many Requests" — Rate limit hit
"Unknown tool: <name>" — Requested a tool that doesn't exist

Scoring & Classification Thresholds

Sleep Quality

Score Range	Classification
85–100	`excellent`
70–84	`good`
50–69	`fair`
0–49	`poor`

Recovery Status

Score Range	Classification
80–100	`excellent`
60–79	`good`
40–59	`fair`
0–39	`poor`

Activity Level

Step Count	Classification
≥ 12,000	`very_active`
8,000–11,999	`active`
5,000–7,999	`moderate`
< 5,000	`sedentary`

Heart Rate Trend

Metric	Threshold
Rising	Last third avg > first third avg by >5%
Falling	Last third avg < first third avg by >5%
Stable	Within ±5%

Example Agent Conversations

Quick Health Check

User: "How am I doing today?"

Agent calls: get_health_summary({})
→ Reviews scores, vitals, and insights
→ "Your sleep was good at 82/100 with 7.2 hours. Recovery is at 75 — you're in good shape for moderate activity. You've taken 8,432 steps so far. Your resting heart rate is 58 bpm, which is normal."

Morning Routine Check

User: "How was my sleep and am I ready for a run?"

Agent calls: get_sleep_analysis({})   +   get_recovery_score({})
→ "You slept 7.2 hours with 88% efficiency — quality is 'good'. Your recovery score is 75/100 (good), so you're ready for a run, but maybe not an intense sprint session."

Real-Time Heart Monitoring

User: "What's my heart rate been like in the last hour?"

Agent calls: get_heart_vitals({ "last_minutes": 60 })
→ "Over the last 60 minutes, your heart rate averaged 78 bpm (range 65–95). Trend is stable. HRV avg is 38ms."

Post-Workout Analysis

User: "How was my heart rate during my workout from 6 to 7 PM?"

Agent calls: get_heart_vitals({ "start_time": "18:00", "end_time": "19:00", "format": "detailed" })
→ Returns individual HR, HRV, and SpO2 readings with timestamps for the workout window.

Historical Check

User: "Compare my recovery yesterday vs today"

Agent calls: get_recovery_score({ "date": "2025-01-26" })   +   get_recovery_score({})
→ "Yesterday your recovery was 62 (good), today it's 75 (good) — trending upward. You're more recovered today."

Temperature Concern

User: "I feel unwell, is my temperature elevated?"

Agent calls: get_temperature_data({})
→ "Your skin temperature deviation from baseline is +0.8°C, which is higher than normal. Average body temperature is 37.1°C. You may want to monitor this."

Project Structure

ultrahuman_mcp/
├── src/
│   ├── index.ts                 # MCP server — tool definitions & request routing
│   ├── ultrahuman-client.ts     # API client — data fetching, filtering, summarization
│   └── types.ts                 # TypeScript interfaces for API responses
├── dist/                        # Compiled JavaScript (generated by `npm run build`)
├── package.json                 # Dependencies & scripts
├── tsconfig.json                # TypeScript configuration
├── .env                         # Your API key (gitignored)
├── .env.example                 # API key template
├── .gitignore
└── README.md

License

MIT License

Available Tools

7 tools

get_activity_dataB

Get activity and movement data including step count, active minutes, movement index, VO2 max, and activity level classification (very_active/active/moderate/sedentary).

Use last_minutes to get recent activity data.

ParametersJSON Schema

Name	Required	Description
`date`	No	Date in YYYY-MM-DD format. Defaults to today if not specified.
`end_time`	No	End time filter in HH:MM format (24-hour). E.g., "17:00" for 5 PM.
`start_time`	No	Start time filter in HH:MM format (24-hour). E.g., "09:00" for 9 AM.
`last_minutes`	No	Filter data to the last X minutes. E.g., 30 for last 30 minutes of data.

TDQS

B3.3/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention whether the operation is read-only, how defaults are handled, what timezone applies, or any other behavioral traits beyond listing data fields. The 'Use last_minutes' hint is the only behavioral note, leaving significant gaps.

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, using only two sentences. It is front-loaded with the primary purpose, and every sentence adds value. It avoids redundancy with the schema while providing necessary context.

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

Completeness3/5

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

Given the lack of an output schema, the description does list key return metrics, which is helpful. However, it does not explain how time filters interact, whether the returned data is aggregated, or what the default behavior is for missing parameters. The description is adequate but not fully complete for a tool with four optional parameters and no output schema.

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

Parameters3/5

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

Schema coverage is 100%, so the baseline is 3. The description adds a small tip about last_minutes but does not contribute additional meaning to date, start_time, or end_time beyond their schema descriptions. This meets the minimum viable level without exceeding it.

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's function: retrieving activity and movement data, listing specific metrics like step count, active minutes, VO2 max, and activity level classification. This distinguishes it from sibling tools such as get_recovery_score or get_temperature_data, making the purpose unambiguous.

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

Usage Guidelines2/5

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

The description does not indicate when to use this tool versus alternatives, nor does it specify exclusions or prerequisites. The only guidance is a note to use last_minutes for recent data, which is a parameter tip rather than tool-selection guidance.

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

get_daily_metricsA

Get ALL raw health metrics from the Ultrahuman API. Returns the complete unprocessed response. Use this only when you need access to data not exposed by other tools.

ParametersJSON Schema

Name	Required	Description
`date`	No	Date in YYYY-MM-DD format. Defaults to today if not specified.
`end_date`	No	End date for range query in YYYY-MM-DD format.
`start_date`	No	Start date for range query in YYYY-MM-DD format.

TDQS

A3.9/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns 'complete unprocessed response' and 'ALL raw health metrics,' which is key behavioral context. However, it doesn't mention potential large response size, rate limits, or error behavior, leaving some gaps.

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 concise sentences. The first states the purpose and scope, the second gives usage guidance. No redundant words, front-loaded with the core action, and every sentence earns its place.

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

Completeness3/5

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

For a simple retrieval tool with three optional parameters and no output schema, the description is reasonably complete but leaves ambiguity about what 'raw health metrics' actually includes. It also doesn't explain how the date parameters interact (single date vs range), though the schema covers their formats.

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

Parameters3/5

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

The input schema already provides full coverage (100%) with clear descriptions for date, end_date, and start_date. The description adds no extra parameter semantics beyond hinting at raw data retrieval, so baseline 3 is appropriate since the schema does the heavy lifting.

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 verb 'Get' and resource 'ALL raw health metrics from the Ultrahuman API,' making the purpose specific. It also distinguishes from sibling tools by emphasizing the 'complete unprocessed response' and directing use to cases where other tools don't expose the needed data.

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 explicitly says 'Use this only when you need access to data not exposed by other tools,' which gives clear when-to-use guidance and implies alternatives (other specific tools). It lacks explicit when-not-to-use examples but the 'only when' phrasing covers the main exclusion.

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

get_health_summaryA

Get a comprehensive health overview with key scores and insights. Returns sleep score, recovery score, activity score, vital signs, and AI-generated health insights. This is the best tool for getting a quick understanding of overall health status.

ParametersJSON Schema

Name	Required	Description
`date`	No	Date in YYYY-MM-DD format. Defaults to today if not specified.
`end_time`	No	End time filter in HH:MM format (24-hour). E.g., "17:00" for 5 PM.
`start_time`	No	Start time filter in HH:MM format (24-hour). E.g., "09:00" for 9 AM.
`last_minutes`	No	Filter data to the last X minutes. E.g., 30 for last 30 minutes of data.

TDQS

A4/5.0

Behavior3/5

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

With no annotations provided, the description carries the burden of disclosing behavior. It lists the return values and mentions AI-generated insights, which adds some transparency. However, it does not explain how the parameters (date, time filters) affect the summary, nor does it mention any access requirements, data freshness, or limitations. A score of 3 is appropriate because it gives a general sense but lacks finer behavioral details.

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 core function 'Get a comprehensive health overview.' Every phrase adds value—listing key outputs and positioning it as the best quick-overview tool. There is no unnecessary fluff or repetition.

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's moderate complexity and the absence of an output schema, the description does well by enumerating the return elements and indicating breadth. It also hints at use cases relative to siblings. It does not describe parameter interactions, but the schema handles those details. The description is complete enough for most users, so a 4 is warranted.

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

Parameters3/5

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

The input schema has 100% description coverage for all four parameters, so the description does not need to add much. The description adds no additional meaning beyond what the schema already provides, such as how filters combine or affect the summary. Per the rubric, baseline is 3 when schema coverage is high, and the description does not exceed that baseline.

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 provides a 'comprehensive health overview' with a specific list of outputs (sleep score, recovery score, activity score, vital signs, AI insights). This distinguishes it from sibling tools like get_recovery_score or get_activity_data, which are specialized. The phrase 'best tool for getting a quick understanding of overall health status' reinforces its primary purpose.

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 implies usage context: use this tool for a broad health summary rather than a specific metric. It states it is 'the best tool' for an overall status, which serves as a recommendation. However, it does not explicitly mention alternatives or when to use sibling tools, so it falls just short of a 5.

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

get_heart_vitalsA

Get heart-related metrics including heart rate, HRV (heart rate variability), and SpO2 (blood oxygen).

By default returns SUMMARY with: avg, min, max, trend, resting HR. Use format="detailed" to get individual readings with timestamps. Use last_minutes to filter to recent data (e.g., last_minutes=30 for last 30 min).

ParametersJSON Schema

Name	Required	Description
`date`	No	Date in YYYY-MM-DD format. Defaults to today if not specified.
`format`	No	Output format. "summary" (default) returns aggregated stats. "detailed" returns raw time-series data.
`end_time`	No	End time filter in HH:MM format (24-hour). E.g., "17:00" for 5 PM.
`start_time`	No	Start time filter in HH:MM format (24-hour). E.g., "09:00" for 9 AM.
`last_minutes`	No	Filter data to the last X minutes. E.g., 30 for last 30 minutes of data.

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations provided, the description carries the transparency burden. It discloses behavior such as the default summary format (avg, min, max, trend, resting HR) and the availability of detailed timestamps. It does not mention rate limits or error scenarios, but adds meaningful behavioral context beyond the schema.

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 and well-structured: three sentences that front-load the purpose, then provide usage details. Every sentence contributes useful information without redundancy or unnecessary elaboration.

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

Completeness3/5

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

The tool has five parameters and no output schema, so the description needs to explain return values and parameter usage. It covers summary vs. detailed and last_minutes, but omits guidance on start_time, end_time, and date parameters, which could leave the agent uncertain about how to choose between time filters. Adequate but with clear gaps.

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 the baseline is 3. The description adds value by explaining the default format, listing summary metrics, and giving a concrete example for last_minutes. This enhances understanding beyond the raw schema definitions.

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's function with a specific verb and resource: 'Get heart-related metrics including heart rate, HRV, and SpO2.' This distinguishes it from sibling tools focused on other health data like temperature or sleep. The scope is unambiguous.

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 gives clear context on how to use the tool, including default summary output, the detailed format option, and last_minutes filtering. It does not explicitly mention alternatives or exclusions, but the heart-specific focus implies when this tool should be used relative to siblings.

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

get_recovery_scoreA

Get recovery metrics indicating physical recovery status. Returns recovery score (0-100) and status classification (excellent/good/fair/poor). Use this to determine if the body is ready for intense activity.

ParametersJSON Schema

Name	Required	Description	Default
`date`	No	Date in YYYY-MM-DD format. Defaults to today if not specified.

TDQS

A4.1/5.0

Behavior3/5

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

No annotations are provided, so the description bears the full burden. It discloses the output format and intended use, but does not mention authentication, rate limits, or explicitly state that it is a safe read operation. The verb 'get' implies read-only, but more detail could be added.

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 long, front-loaded with the action, and contains no filler. Every sentence contributes value: what it does, what it returns, and when to use it.

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

Completeness5/5

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

The tool is simple with one optional parameter and no output schema. The description fully covers the purpose, return values, and usage context, making it self-sufficient for an agent to select and invoke the tool correctly.

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

Parameters3/5

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

The schema fully describes the 'date' parameter with defaults and format, achieving 100% coverage. The description does not add extra parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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 retrieves recovery metrics, specifically a score (0-100) and a status classification. This distinguishes it from sibling tools focused on temperature, heart, sleep, activity, and general health metrics.

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 explicitly says 'Use this to determine if the body is ready for intense activity,' providing a clear use case. It does not mention alternatives or exclusions, so it falls short of a 5, but the context is unambiguous.

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

get_sleep_analysisA

Get comprehensive sleep data including sleep score, duration, efficiency, sleep stages (REM, deep, light), sleep cycles, and quality assessment. Returns a summary with quality indicator (excellent/good/fair/poor).

ParametersJSON Schema

Name	Required	Description	Default
`date`	No	Date in YYYY-MM-DD format. Defaults to today if not specified.

TDQS

A3.7/5.0

Behavior3/5

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

With no annotations, the description carries the full burden. It discloses that the tool returns a summary and quality indicator, implying a read-only operation. However, it does not mention potential absence of data, date range limitations, or any safety/privacy considerations. The return format is partially specified.

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

Conciseness4/5

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

The description is compact: two sentences covering the data fields and the quality indicator. Each listed item adds meaning, though the first sentence is a bit dense with list-like structure. Efficient overall.

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?

For a simple read tool with one optional param and no output schema, the description lists the key return fields and quality categories. It does not specify exact output format or edge cases, but for a sleep analysis tool, it provides sufficient context. Minor gaps exist in describing error behavior or data availability.

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

Parameters3/5

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

Schema description coverage is 100%, with the single 'date' parameter fully described (format and default). The tool description adds high-level context about the data returned but does not elaborate on parameter behavior beyond what the schema already states. Baseline 3 is appropriate.

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 a specific verb 'Get' and clearly identifies the resource as 'sleep data', listing concrete data elements (sleep score, duration, efficiency, stages, cycles, quality). This distinguishes it from sibling tools focused on recovery, temperature, metrics, summary, heart vitals, and activity.

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

Usage Guidelines3/5

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

The description implies use when sleep analysis is needed, but provides no explicit guidance on when to prefer this over sibling tools like get_daily_metrics or get_health_summary. No exclusions or alternative recommendations are given.

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

get_temperature_dataA

Get body temperature metrics including skin temperature readings, temperature deviation from baseline, and average body temperature. Useful for detecting illness or stress.

Use last_minutes to get recent temperature data.

ParametersJSON Schema

Name	Required	Description
`date`	No	Date in YYYY-MM-DD format. Defaults to today if not specified.
`end_time`	No	End time filter in HH:MM format (24-hour). E.g., "17:00" for 5 PM.
`start_time`	No	Start time filter in HH:MM format (24-hour). E.g., "09:00" for 9 AM.
`last_minutes`	No	Filter data to the last X minutes. E.g., 30 for last 30 minutes of data.

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description bears the full responsibility. It describes the metrics returned and implies a read-only 'get' operation, but it doesn't disclose response format, timezone handling, or potential errors. This is adequate for a simple read tool but lacks depth.

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 concise sentences with no fluff. It front-loads the core purpose and ends with a practical hint. Every word contributes value.

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 absence of an output schema and annotations, the description covers the main metrics and typical use case well. It doesn't explain return field names or edge cases, but for a straightforward temperature data tool, it's substantially complete.

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

Parameters3/5

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

All four parameters are already documented in the schema with clear descriptions (100% coverage). The description adds only a redundant tip about last_minutes, which does not meaningfully exceed what the schema already states. Baseline 3 is appropriate.

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 retrieves body temperature metrics, specifically naming skin temperature, deviation from baseline, and average body temperature. This is a specific verb+resource that distinguishes it from sibling health tools like heart vitals or sleep analysis.

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?

Provides clear context for when to use the tool ('useful for detecting illness or stress') and gives specific parameter guidance ('Use last_minutes to get recent temperature data'). It does not mention alternatives or exclusions, but the use case is sufficiently clear.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

7 tool updatesv1.0.0Aug 9, 2026
- First observedget_activity_data
- First observedget_daily_metrics
- First observedget_health_summary
- First observedget_heart_vitals
- First observedget_recovery_score
- First observedget_sleep_analysis
- First observedget_temperature_data

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-08-09 17:40 across 7 tools

Disambiguation4/5

Each tool targets a specific health metric (recovery, temperature, heart, sleep, activity), but get_health_summary and get_daily_metrics overlap with the specific tools, though descriptions clarify their distinct purposes as summary and raw access.

Naming Consistency5/5

All tools follow a consistent get_<metric> naming pattern, making it easy to predict tool names and purposes.

Tool Count5/5

Seven tools is well-scoped for a health data server, covering the major health domains without unnecessary redundancy.

Completeness4/5

The tool set covers key health metrics (recovery, temperature, heart, sleep, activity) and provides both summary and raw data access. Minor gaps include lack of historical trend queries beyond recent minutes, but core read-only health tracking is well covered.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

freddyOAuth
coach.freddy
Connect your wearables, rings and training apps, then ask your AI about your own health data.
Health & Wellness Fitness Tracking
2
Wellness Project AOAuth
ai.wellnessproject
Connect your health, fitness, nutrition, sleep, and wearable data to your AI assistant.
AI & Machine Learning Fitness Tracking Health & Wellness
7422
pronto-stream A
io.github.nmxmxh
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
Agent Orchestration Cryptocurrency Finance
151
MCP for OuraOAuth
link.smirnov
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Health & Wellness Fitness Tracking
2

Related MCP Servers

Oura MCP Server
koji117
A
license
Not graded
quality
D
maintenance
Provides access to Oura Ring health data, including sleep, activity, readiness, and stress metrics via the Model Context Protocol. It enables users to query their personal biometric information and daily health summaries through natural language in MCP-compatible clients.
Updated 6 months ago (2026-03-07 02:28 UTC)
681 npm
MIT
Ultrahuman MCP Server
Health & Wellness Fitness Tracking
Vodolazkyi
A
license
Not graded
quality
D
maintenance
Provides access to Ultrahuman health and fitness data through standardized MCP tools, enabling AI assistants to retrieve metrics like sleep, movement, heart rate, and glucose.
Updated a year ago (2025-09-08 12:21 UTC)
1
MIT
Oura MCP
Health & Wellness Fitness Tracking
davidmosiah
A
license
B
quality
A
maintenance
Local-first MCP server that connects AI agents to your Oura Ring readiness, sleep, activity, and HRV data. Tokens never leave your machine.
Updated 5 days ago (2026-09-10 13:10 UTC)
27
88 npm
2
MIT
Sensor Bio MCP Serverofficial
Health & Wellness Fitness Tracking
GetSensr-io
A
license
A
quality
D
maintenance
Connects Sensor Bio wearable data to AI assistants via the Model Context Protocol, enabling queries about sleep, heart rate, activity, and other biometrics.
Updated 14 days ago (2026-09-01 06:14 UTC)
13
1
MIT

💍 Ultrahuman Ring MCP Server

Table of Contents

Architecture Overview

Prerequisites

Quick Start

1. Install Dependencies

2. Configure API Key

3. Build & Start

MCP Client Configuration

Claude Desktop

Cursor / Windsurf / Other MCP Clients

Common Parameters

Time Filtering Behavior

Tools Reference

1. get_health_summary

Input Schema

Response Schema

Insight Generation Rules

2. get_heart_vitals

Input Schema

Response Schema — Summary (default)

Response Schema — Detailed (format: "detailed")

Trend Calculation

3. get_sleep_analysis

Input Schema

Response Schema

Quality Classification

4. get_activity_data

Input Schema

Response Schema

Activity Level Classification

5. get_recovery_score

Input Schema

Response Schema

Recovery Status Classification

6. get_temperature_data

Input Schema

Response Schema

7. get_daily_metrics

Input Schema

Response Schema

Tool Selection Guide

Recommended Agent Workflow

Response Conventions

TimeSeriesSummary Object

Null Values

Error Responses

Scoring & Classification Thresholds

Sleep Quality

Recovery Status

Activity Level

Heart Rate Trend

Example Agent Conversations

Quick Health Check

Morning Routine Check

Real-Time Heart Monitoring

Post-Workout Analysis

Historical Check

Temperature Concern

Project Structure

License

Links

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Sensor Bio MCP Serverofficial

1. `get_health_summary`

2. `get_heart_vitals`

Response Schema — Detailed (`format: "detailed"`)

3. `get_sleep_analysis`

4. `get_activity_data`

5. `get_recovery_score`

6. `get_temperature_data`

7. `get_daily_metrics`