Pulsyn MCP Server

Access your Pulsyn smart ring health data directly in AI assistants via the Model Context Protocol.

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

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):

{
  "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:

bunx pulsyn-mcp-server

Using npm

npm install -g pulsyn-mcp-server
pulsyn-mcp-server

From Source

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:

{
  "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

# 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 for guidelines.

License

MIT License - see LICENSE for details.

Links

• Pulsyn Website
• API Documentation
• Model Context Protocol
• GitHub Repository