Ultrahuman-MCP by Monasterolo21 - MCP Server

Ultrahuman MCP Server

A Model Context Protocol (MCP) server for fetching health and fitness metrics from the Ultrahuman API. Built with TypeScript and designed for production use.

🚀 Quick Start

Clone the repository
Install dependencies:
```
bun install
```
Build the project:
```
bun run build
```
Configure your environment variables (see Configuration section)
Add to Claude Desktop (see Usage section)

🔑 Getting Started with Ultrahuman API

Before you can use this MCP server, you'll need to obtain your Ultrahuman credentials. Follow these steps:

Step 1: Get Your Ultrahuman Email

Open the Ultrahuman app on your device
Navigate to the Profile tab at the bottom of the screen
Tap the settings icon (cog icon) in the top left corner
Your email address will be displayed at the top of the settings screen
Copy this email address - you'll need it for configuration

Step 2: Request API Key and Partner ID

You must obtain an API key and Partner ID from Ultrahuman by contacting them through one of these methods:

Email: Send a request to support@ultrahuman.com
In-app chat: Use the customer service chat within the Ultrahuman app

Important: Make sure to include your Ultrahuman email address in your request to speed up the response time.

Once you receive your API key and Partner ID, keep them secure and private.

Step 3: Configure Partner ID in App

Open the Ultrahuman app on your device
Navigate to the Profile tab at the bottom of the screen
Tap the settings icon (cog icon) in the top left corner
Scroll down to find the Partner ID field
Enter the Partner ID code you received from Ultrahuman

Step 4: Configure the MCP Server

Now you can configure this MCP server with your credentials:

Set your environment variables (see Configuration section below)
Build and run the server
Add it to Claude Desktop with your API credentials

You're all set to start fetching your health data!

✨ Key Features

Fetch comprehensive health metrics from Ultrahuman API
Heart rate, sleep, steps, temperature, and HRV monitoring
Built with TypeScript for type safety
Bun for fast testing and development
Biome for linting and formatting
Clean, maintainable project structure

📂 Project Structure

ultrahuman-mcp/
├── src/
│   ├── tools/          # MCP tools implementation
│   │   └── ultrahumanMetrics/  # Ultrahuman API integration
│   ├── utils/          # Shared utilities
│   ├── main.ts         # Server entry point
│   └── types.ts        # Shared type definitions
├── scripts/            # Build and utility scripts
├── biome.json          # Linting configuration
├── tsconfig.json       # TypeScript configuration
└── package.json        # Project dependencies

⚙️ Configuration

This server requires environment variables to authenticate with the Ultrahuman API:

ULTRAHUMAN_AUTH_TOKEN: Your Ultrahuman API authorization token
ULTRAHUMAN_USER_EMAIL: The email address of the Ultrahuman user whose data you want to fetch

The API base URL is configured to https://partner.ultrahuman.com/api/v1.

🔧 Available Tools

`ultrahuman_metrics`

Fetches health and fitness metrics from the Ultrahuman API for a specific date. The user email is configured via environment variable, so you only need to specify the date to retrieve comprehensive health data.

Parameters:

date: Date in YYYY-MM-DD format to fetch metrics for (e.g., '2025-06-19')

Example Usage:

{
  "name": "ultrahuman_metrics",
  "arguments": {
    "date": "2025-06-19"
  }
}

📊 Available Health Data

The API provides comprehensive health metrics including:

Heart Rate: Continuous heart rate monitoring with timestamps
Skin Temperature: Body temperature variations throughout the day
HRV (Heart Rate Variability): Heart rate variability measurements
Steps: Step count data with activity tracking
Sleep Data: Detailed sleep analysis including:
- Sleep stages (Deep, Light, REM, Awake)
- Sleep efficiency and quality metrics
- Heart rate and HRV during sleep
- Temperature variations during sleep
Recovery Index: Overall recovery score
Movement Index: Activity and movement metrics
VO2 Max: Cardiovascular fitness indicator

💻 Usage with Claude Desktop

Build the project:
```
bun run build
```

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ultrahuman": {
      "command": "node",
      "args": ["/path/to/your/project/dist/main.js"],
      "env": {
        "ULTRAHUMAN_AUTH_TOKEN": "your_token_here",
        "ULTRAHUMAN_USER_EMAIL": "your_email@example.com"
      }
    }
  }
}

🧪 Testing

You can test the server by running it directly:

node dist/main.js

The server will listen for MCP requests on stdio and provide the ultrahuman_metrics tool to fetch health data from the API.

🛠️ Development

Run tests: bun test
Format code: bun run format
Lint code: bun run lint
Build project: bun run build

📜 Version Management

This project uses standard-version for automated version management. Run bun run release to create a new version.

Commit Message Format

feat: New feature (bumps minor version)
fix: Bug fix (bumps patch version)
BREAKING CHANGE: Breaking change (bumps major version)

📦 Publishing to npm

Ensure you're logged in to npm:
```
npm login
```
Build the project:
```
bun run build
```
Publish the package:
```
npm publish
```

Installing from npm (after publishing)

Add to your Claude Desktop config:

{
  "mcpServers": {
    "ultrahuman": {
      "command": "npx",
      "args": ["-y", "ultrahuman-mcp"],
      "env": {
        "ULTRAHUMAN_AUTH_TOKEN": "your_token_here",
        "ULTRAHUMAN_USER_EMAIL": "your_email@example.com"
      }
    }
  }
}