MCP 服务器

Ultrahuman MCP Server

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.

README

Ultrahuman MCP Server

A Model Context Protocol (MCP) server that provides access to Ultrahuman API data. This server allows AI assistants and applications to interact with Ultrahuman health and fitness data through standardized MCP tools.

Features

Complete Health Metrics Access: Sleep, movement, heart rate, HRV, glucose, and more
Specialized Tools: Dedicated tools for different data types (sleep, movement, glucose, heart metrics)
Error Handling: Robust error handling with detailed error messages
Date Validation: Automatic validation of date formats
Environment Configuration: Flexible configuration through environment variables

Available Tools

Core Tools

get_default_user_metrics(date) - Get all health metrics for default user (from env) on a specific date
get_user_metrics(email, date) - Get all health metrics for a user on a specific date
get_sleep_data(email, date) - Get sleep-specific metrics
get_movement_data(email, date) - Get movement and activity data
get_glucose_metrics(email, date) - Get glucose-related metrics
get_heart_metrics(email, date) - Get heart rate, HRV, and recovery data

Resources

ultrahuman://api-info - Information about the Ultrahuman Partnership API

Available Metrics

The server provides access to the following health metrics:

Sleep Data - Sleep patterns, quality, duration
Movement Data - Activity levels, movement patterns
Heart Rate - Continuous heart rate monitoring
HRV - Heart Rate Variability measurements
Temperature - Body temperature readings
Steps - Daily step count
Glucose - Blood glucose levels (from CGM)
Metabolic Score - Overall metabolic health score
Glucose Variability (%) - Blood sugar stability
Average Glucose (mg/dL) - Daily glucose average
HbA1c - Long-term glucose control indicator
Time in Target (%) - Time spent in target glucose range
Recovery Index - Recovery status metrics
Movement Index - Movement quality assessment
VO2 Max - Cardiovascular fitness measure

Setup

Prerequisites

Ultrahuman API Access:
- Authorization key (40-character alpha-numeric string)
- Data sharing code from users
- User email with granted access
- 📋 See detailed setup instructions: API_SETUP.md
- Contact support@ultrahuman.com for API access
- API documentation: https://blog.ultrahuman.com/blog/accessing-the-ultrahuman-partnership-api/
Python 3.11+

Installation

Clone this repository:

git clone https://github.com/Vodolazkyi/Ultrahuman-Server.git
cd Ultrahuman-Server

Install dependencies:

pip install -r requirements.txt

Configure environment variables:

cp env.example .env
# Edit .env with your Ultrahuman API credentials

Run the server:

python main.py

The server will start on http://localhost:8000/mcp by default.

Environment Variables

Variable	Description	Default
`ULTRAHUMAN_AUTH_KEY`	Your 40-character authorization key	Required
`ULTRAHUMAN_BASE_URL`	API base URL	`https://partner.ultrahuman.com/api/v1`
`ULTRAHUMAN_DEFAULT_EMAIL`	Default user email for testing	Optional
`PORT`	Server port	`8000`

Usage Examples

Using with MCP Client

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["main.py"],
        env={"ULTRAHUMAN_AUTH_KEY": "your_key_here"}
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the connection
            await session.initialize()
            
            # Get user metrics
            result = await session.call_tool(
                "get_user_metrics",
                {
                    "email": "user@example.com",
                    "date": "2024-01-15"
                }
            )
            print(result)

if __name__ == "__main__":
    asyncio.run(main())

Tool Examples

Get Complete Metrics

# Get all metrics for a user
result = await session.call_tool("get_user_metrics", {
    "email": "user@example.com",
    "date": "2024-01-15"
})

Get Sleep Data Only

# Get sleep-specific data
result = await session.call_tool("get_sleep_data", {
    "email": "user@example.com", 
    "date": "2024-01-15"
})

Get Glucose Metrics

# Get glucose-related metrics
result = await session.call_tool("get_glucose_metrics", {
    "email": "user@example.com",
    "date": "2024-01-15"
})

API Response Format

All tools return a consistent response format:

{
    "success": true,
    "email": "user@example.com",
    "date": "2024-01-15",
    "metrics": {
        // ... actual metrics data
    }
}

On error:

{
    "success": false,
    "email": "user@example.com", 
    "date": "2024-01-15",
    "error": "Error description"
}

Deployment

Railway Deployment

This server is configured for deployment on Railway:

Connect your GitHub repository to Railway
Set environment variables in Railway dashboard:
- ULTRAHUMAN_AUTH_KEY
- ULTRAHUMAN_BASE_URL (optional)
Deploy automatically from main branch

Docker Deployment

# Build the image
docker build -t ultrahuman-mcp .

# Run the container
docker run -p 8000:8000 \
  -e ULTRAHUMAN_AUTH_KEY=your_key_here \
  ultrahuman-mcp