Pulsyn MCP Server

🚀 Pulsyn MCP Server

Access your Pulsyn smart ring health data directly in AI assistants via the Model Context Protocol. This server allows seamless integration, providing various health - related features.

✨ Features

• Sleep Tracking: Duration, stages (deep/light/REM/awake), quality scores, and 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, and 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

📚 Documentation

Environment Variables

Config File

Alternatively, create ~/.config/pulsyn-mcp-server/config.json:

{
  "apiToken": "psk_your_token_here",
  "baseUrl": "https://www.getpulsyn.com/api/v1",
  "debug": false
}

💻 Usage Examples

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)

🔧 Technical Details

Rate Limits

The Pulsyn API enforces different rate limits based on account tier:

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

🛠️ 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