Ultrahuman Mcp

Ultrahuman MCP Server

一个用于从 Ultrahuman API 获取健康和健身指标的模型上下文协议（MCP）服务。使用 TypeScript 构建，专为生产环境设计。

🚀 快速开始

1. 克隆仓库
2. 安装依赖：

   bun install
   

3. 构建项目：

   bun run build
   

4. 配置环境变量（参见“配置”部分）
5. 添加到 Claude Desktop（参见“使用方法”部分）

🔑 开始使用 Ultrahuman API

使用此 MCP 服务之前，你需要获取 Ultrahuman 凭据。请按以下步骤操作：

第 1 步：获取你的 Ultrahuman 邮箱地址

1. 在设备上打开 Ultrahuman 应用
2. 前往屏幕底部的 Profile 选项卡
3. 点击左上角的设置图标（齿轮图标）
4. 你的邮箱地址会显示在设置屏幕顶部
5. 复制此邮箱地址——配置时需要用到

第 2 步：申请 API 密钥和 Partner ID

你必须通过以下任一方式联系 Ultrahuman，以获取 API 密钥和 Partner ID：

• 电子邮件：向 [email protected] 发送申请
• 应用内聊天：使用 Ultrahuman 应用内的客服聊天功能

重要提示：请在申请中注明你的 Ultrahuman 邮箱地址，以便加快回复速度。

收到 API 密钥和 Partner ID 后，请妥善保管，切勿泄露。

第 3 步：在应用中配置 Partner ID

1. 在设备上打开 Ultrahuman 应用
2. 前往屏幕底部的 Profile 选项卡
3. 点击左上角的设置图标（齿轮图标）
4. 向下滚动，找到 Partner ID 字段
5. 输入你从 Ultrahuman 收到的 Partner ID 代码

第 4 步：配置 MCP 服务

现在可以使用你的凭据配置此 MCP 服务：

1. 设置环境变量（参见下方“配置”部分）
2. 构建并运行服务
3. 使用你的 API 凭据将其添加到 Claude Desktop

一切就绪，现在可以开始获取你的健康数据了！

✨ 主要功能

• 从 Ultrahuman API 获取全面的健康指标
• 监测心率、睡眠、步数、体温和 HRV
• 使用 TypeScript 构建，确保类型安全
• 使用 Bun 加快测试和开发
• 使用 Biome 进行代码检查和格式化
• 项目结构清晰，易于维护

📂 项目结构

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

⚙️ 配置

此服务需要使用环境变量向 Ultrahuman API 进行身份验证：

• ULTRAHUMAN_AUTH_TOKEN：你的 Ultrahuman API 授权令牌
• ULTRAHUMAN_USER_EMAIL：要获取其数据的 Ultrahuman 用户的邮箱地址

API 基础 URL 配置为 https://partner.ultrahuman.com/api/v1。

🔧 可用工具

ultrahuman_metrics

从 Ultrahuman API 获取指定日期的健康和健身指标。用户邮箱通过环境变量配置，因此你只需指定日期，即可获取全面的健康数据。

参数：

• date：要获取指标的日期，格式为 YYYY-MM-DD（例如，'2025-06-19'）

使用示例：

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

📊 可获取的健康数据

API 提供全面的健康指标，包括：

• 心率：带时间戳的连续心率监测数据
• 皮肤温度：全天的体温变化
• HRV（心率变异性）：心率变异性测量数据
• 步数：步数数据及活动追踪
• 睡眠数据：详细的睡眠分析，包括：
  • 睡眠阶段（深睡、浅睡、REM、清醒）
  • 睡眠效率和质量指标
  • 睡眠期间的心率和 HRV
  • 睡眠期间的温度变化
• 恢复指数：总体恢复评分
• 活动指数：活动和运动指标
• VO2 Max：心血管健康指标

💻 在 Claude Desktop 中使用

1. 构建项目：

   bun run build
   

2. 添加到 Claude Desktop 配置文件（~/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": "[email protected]"
         }
       }
     }
   }
   

🧪 测试

可以直接运行服务进行测试：

node dist/main.js

服务将在 stdio 上监听 MCP 请求，并提供 ultrahuman_metrics 工具，从 API 获取健康数据。

🛠️ 开发

• 运行测试：bun test
• 格式化代码：bun run format
• 检查代码：bun run lint
• 构建项目：bun run build

📜 版本管理

本项目使用 standard-version 自动管理版本。运行 bun run release 创建新版本。

提交消息格式

• feat：新功能（次版本号递增）
• fix：修复 Bug（补丁版本号递增）
• BREAKING CHANGE：破坏性更改（主版本号递增）

📦 发布到 npm

1. 确保已登录 npm：

   npm login
   

2. 构建项目：

   bun run build
   

3. 发布软件包：

   npm publish
   

从 npm 安装（发布后）

添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "ultrahuman": {
      "command": "npx",
      "args": ["-y", "ultrahuman-mcp"],
      "env": {
        "ULTRAHUMAN_AUTH_TOKEN": "your_token_here",
        "ULTRAHUMAN_USER_EMAIL": "[email protected]"
      }
    }
  }
}