内容
# 脉动MCP服务器
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
[](https://github.com/getpulsyn/pulsyn-mcp-server/actions/workflows/ci.yml)
通过[模型上下文协议](https://modelcontextprotocol.io)在AI助手直接访问您的脉动智能戒指健康数据。
## 功能
- **睡眠跟踪** - 时长、阶段（深/浅/REM/清醒）、质量评分、效率
- **心率变异性分析** - 心率变异性测量，用于恢复和压力洞察
- **心率** - 持续监测和静息心率
- **活动数据** - 步数、热量、活跃分钟数、距离
- **准备度评分** - 结合睡眠、心率变异性和恢复的日常准备度
- **健康总结** - 全面的日常健康快照
## 快速入门
### 1. 获取您的API令牌
1. 打开 **脉动移动应用**
2. 导航到 **设置 → API访问**
3. 点击 **"创建新令牌"**
4. 选择 `read:health_data` 范围
5. 复制令牌（以 `psk_` 开头）
### 2. 配置令牌
```bash
export PULSYN_API_TOKEN=psk_您的令牌_在此
```
### 3. 添加到Claude桌面版
将以下内容添加到您的Claude桌面版配置中（`~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS上或 `%APPDATA%/Claude/claude_desktop_config.json` 在Windows上）：
```json
{
"mcpServers": {
"pulsyn": {
"command": "bunx",
"args": ["pulsyn-mcp-server"],
"env": {
"PULSYN_API_TOKEN": "psk_您的令牌_在此"
}
}
}
}
```
## 安装
### 使用bunx（推荐）
无需安装 - 直接运行：
```bash
bunx pulsyn-mcp-server
```
### 使用npm
```bash
npm install -g pulsyn-mcp-server
pulsyn-mcp-server
```
### 从源代码
```bash
git clone https://github.com/getpulsyn/pulsyn-mcp-server.git
cd pulsyn-mcp-server
bun install
bun run build
```
## 配置
### 环境变量
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `PULSYN_API_TOKEN` | 是 | 您的脉动API令牌（`psk_...`） |
| `PULSYN_API_URL` | 否 | 自定义API网址（默认：`https://www.getpulsyn.com/api/v1`） |
| `PULSYN_DEBUG` | 否 | 启用调试日志（`true`/`false`） |
### 配置文件
或者，创建 `~/.config/pulsyn-mcp-server/config.json`:
```json
{
"apiToken": "psk_您的令牌_在此",
"baseUrl": "https://www.getpulsyn.com/api/v1",
"debug": false
}
```
## 可用工具
### 获取睡眠数据
检索具有时长、阶段、质量评分和效率的睡眠会话。
**参数：**
- `days` （数字）：获取的天数（默认：7，最大：90）
- `limit` （数字）：最大结果数（默认：100，最大：1000）
**示例提示：**
- "显示我上周的睡眠数据"
- "昨晚我的深度睡眠百分比是多少？"
### 获取心率变异性数据
获取心率变异性测量值 - 恢复和压力的关键指标。
**参数：**
- `days` （数字）：获取的天数（默认：7，最大：90）
- `limit` （数字）：最大结果数（默认：100，最大：1000）
**示例提示：**
- "这个月我的平均心率变异性是多少？"
- "显示我过去一周的心率变异性趋势"
### 获取心率数据
获取连续心率测量值，包括静息心率。
**参数：**
- `days` （数字）：获取的天数（默认：7，最大：90）
- `limit` （数字）：最大结果数（默认：100，最大：1000）
### 获取活动数据
获取日常活动指标：步数、热量、活跃时间、距离。
**参数：**
- `days` （数字）：获取的天数（默认：7，最大：90）
- `limit` （数字）：最大结果数（默认：100，最大：1000）
### 获取准备度评分
获取结合睡眠、心率变异性和恢复的日常准备度评分。
**参数：**
- `days` （数字）：获取的天数（默认：7，最大：90）
- `limit` （数字）：最大结果数（默认：100，最大：1000）
### 获取健康总结
获取特定日期的综合健康总结。
**参数：**
- `date` （字符串）：YYYY-MM-DD格式的日期（默认：今天）
## 速率限制
脉动API根据账户层级强制执行不同的速率限制：
| 功能 | 免费用户 | 付费用户 |
|---------|-----------|-----------|
| **速率限制** | 1请求/秒/端点 | 1,000请求/小时/密钥 |
| **范围** | 每个账户，每个端点 | 每个API密钥 |
| **多个端点** | ✅ 可以同时调用不同的端点 | ✅ 没有每个端点的限制 |
| **突发请求** | ❌ 必须等待1秒后才能请求相同的端点 | ✅ 可以快速连续请求 |
| **API密钥** | 1密钥 | 最多10个密钥 |
| **最大吞吐量** | ~6个端点/秒 | 10,000请求/小时（使用10个密钥） |
**错误处理：**
- **429 请求过多** 在超出限制时返回
- 具有指数退避和抖动的自动重试
- 尊重速率限制恢复的 `Retry-After` 头部
## 安全
- **本地存储**：令牌仅存储在您的机器上
- **只读访问**：无法修改您的健康数据
- **仅HTTPS**：所有通信都加密
- **令牌撤销**：在脉动应用中随时撤销
## 故障排除
| 问题 | 解决方案 |
|-------|----------|
| "未配置API令牌" | 设置 `PULSYN_API_TOKEN` 或创建配置文件 |
| "令牌无效或已过期" | 在脉动应用中生成新令牌 |
| "速率限制已超过" | 等待重置（最大1小时） |
| 连接超时 | 检查互联网连接 |
## 开发
```bash
# 以开发模式运行
bun run dev
# 运行测试
bun test
# 类型检查
bun run typecheck
# 代码 lint
bun run lint
# 构建生产版本
bun run build
```
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
## 许可证
MIT 许可证 - 请参阅 [LICENSE](LICENSE) 获取详细信息。
## 链接
- [脉动官网](https://www.getpulsyn.com)
- [API 文档](https://www.getpulsyn.com/docs/api)
- [模型上下文协议](https://modelcontextprotocol.io)
- [GitHub 仓库](https://github.com/getpulsyn/pulsyn-mcp-server)
