Content
# Pulsyn MCP Server
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
[](https://github.com/getpulsyn/pulsyn-mcp-server/actions/workflows/ci.yml)
Access your Pulsyn smart ring health data directly in AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io).
## Features
- **Sleep Tracking** - Duration, stages (deep/light/REM/awake), quality scores, efficiency
- **HRV Analysis** - Heart rate variability measurements for recovery and stress insights
- **Heart Rate** - Continuous monitoring and resting heart rate
- **Activity Data** - Steps, calories, active minutes, distance
- **Readiness Scores** - Daily readiness combining sleep, HRV, and recovery
- **Health Summaries** - Comprehensive daily health snapshots
## Quick Start
### 1. Get Your API Token
1. Open the **Pulsyn mobile app**
2. Navigate to **Settings → API Access**
3. Tap **"Create New Token"**
4. Select `read:health_data` scope
5. Copy the token (starts with `psk_`)
### 2. Configure the Token
```bash
export PULSYN_API_TOKEN=psk_your_token_here
```
### 3. Add to Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%/Claude/claude_desktop_config.json` on Windows):
```json
{
"mcpServers": {
"pulsyn": {
"command": "bunx",
"args": ["pulsyn-mcp-server"],
"env": {
"PULSYN_API_TOKEN": "psk_your_token_here"
}
}
}
}
```
## Installation
### Using bunx (Recommended)
No installation needed - runs directly:
```bash
bunx pulsyn-mcp-server
```
### Using npm
```bash
npm install -g pulsyn-mcp-server
pulsyn-mcp-server
```
### From Source
```bash
git clone https://github.com/getpulsyn/pulsyn-mcp-server.git
cd pulsyn-mcp-server
bun install
bun run build
```
## Configuration
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `PULSYN_API_TOKEN` | Yes | Your Pulsyn API token (`psk_...`) |
| `PULSYN_API_URL` | No | Custom API URL (default: `https://www.getpulsyn.com/api/v1`) |
| `PULSYN_DEBUG` | No | Enable debug logging (`true`/`false`) |
### Config File
Alternatively, create `~/.config/pulsyn-mcp-server/config.json`:
```json
{
"apiToken": "psk_your_token_here",
"baseUrl": "https://www.getpulsyn.com/api/v1",
"debug": false
}
```
## Available Tools
### get_sleep_data
Retrieve sleep sessions with duration, stages, quality scores, and efficiency.
**Parameters:**
- `days` (number): Days to fetch (default: 7, max: 90)
- `limit` (number): Max results (default: 100, max: 1000)
**Example prompts:**
- "Show me my sleep data from the last week"
- "What was my deep sleep percentage last night?"
### get_hrv_data
Get heart rate variability measurements - a key indicator of recovery and stress.
**Parameters:**
- `days` (number): Days to fetch (default: 7, max: 90)
- `limit` (number): Max results (default: 100, max: 1000)
**Example prompts:**
- "What's my average HRV this month?"
- "Show my HRV trend over the past week"
### get_heart_rate_data
Get continuous heart rate measurements including resting heart rate.
**Parameters:**
- `days` (number): Days to fetch (default: 7, max: 90)
- `limit` (number): Max results (default: 100, max: 1000)
### get_activity_data
Get daily activity metrics: steps, calories, active time, distance.
**Parameters:**
- `days` (number): Days to fetch (default: 7, max: 90)
- `limit` (number): Max results (default: 100, max: 1000)
### get_readiness_score
Get daily readiness scores combining sleep, HRV, and recovery.
**Parameters:**
- `days` (number): Days to fetch (default: 7, max: 90)
- `limit` (number): Max results (default: 100, max: 1000)
### get_health_summary
Get a comprehensive health summary for a specific date.
**Parameters:**
- `date` (string): Date in YYYY-MM-DD format (default: today)
## Rate Limits
The Pulsyn API enforces different rate limits based on account tier:
| Feature | Free Users | Paid Users |
|---------|-----------|-----------|
| **Rate Limit** | 1 request/second per endpoint | 1,000 requests/hour per key |
| **Scope** | Per account, per endpoint | Per API key |
| **Multiple Endpoints** | ✅ Can call different endpoints simultaneously | ✅ No per-endpoint restrictions |
| **Burst Requests** | ❌ Must wait 1 second between same-endpoint requests | ✅ Can make rapid successive requests |
| **API Keys** | 1 key | Up to 10 keys |
| **Max Throughput** | ~6 endpoints/second | 10,000 requests/hour (with 10 keys) |
**Error Handling:**
- **429 Too Many Requests** returned when limit exceeded
- Automatic retry with exponential backoff and jitter
- Respects `Retry-After` header for rate limit recovery
## Security
- **Local-only storage**: Tokens stored only on your machine
- **Read-only access**: Cannot modify your health data
- **HTTPS only**: All communication encrypted
- **Token revocation**: Revoke anytime in Pulsyn app
## Troubleshooting
| Issue | Solution |
|-------|----------|
| "No API token configured" | Set `PULSYN_API_TOKEN` or create config file |
| "Invalid or expired token" | Generate a new token in Pulsyn app |
| "Rate limit exceeded" | Wait for reset (max 1 hour) |
| Connection timeout | Check internet connection |
## Development
```bash
# Run in development mode
bun run dev
# Run tests
bun test
# Type check
bun run typecheck
# Lint code
bun run lint
# Build for production
bun run build
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
MIT License - see [LICENSE](LICENSE) for details.
## Links
- [Pulsyn Website](https://www.getpulsyn.com)
- [API Documentation](https://www.getpulsyn.com/docs/api)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [GitHub Repository](https://github.com/getpulsyn/pulsyn-mcp-server)
