How do I use ultrahuman_mcp?

1. Click on "Install 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 Related Servers Score Discussions

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

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

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/crixalis17/ultrahuman_mcp'

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

💍 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

Maintenance

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

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`