CPAP-analyst-MCP

Joc007/CPAP-analyst-MCP

3.2

If you are the rightful owner of CPAP-analyst-MCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP server for analyzing CPAP therapy data from Lowenstein/Weinmann devices.

Tools
4
Resources
0
Prompts
0

CPAP Analyst MCP Server

MCP server for analyzing CPAP therapy data from Lowenstein/Weinmann devices

Answer the key question: "Should I continue with CPAP treatment?"

What This Does

This MCP server parses data from your CPAP machine's SD card and provides natural language analysis through Claude Code. Ask questions like:

  • "How's my CPAP therapy going?"
  • "Show me nights with high leak rates"
  • "Should I continue with CPAP treatment?"
  • "What's my average AHI over the last month?"

Supported Devices

  • Lowenstein Medical Prisma SMART (CPAP/APAP modes)
  • Lowenstein Medical PrismaSmartMax
  • Other Weinmann/Lowenstein devices using TDF format

The parser reads WM_DATA.TDF files from your CPAP SD card.

Installation

Prerequisites

  • macOS (tested on macOS 14+)
  • Python 3.10+
  • Claude Code CLI (for MCP integration)

Step 1: Clone and Install

# Clone the repository
cd ~
git clone https://github.com/Joc007/CPAP-analyst-MCP.git
cd CPAP-analyst-MCP

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

Step 2: Sync Your CPAP Data

# Insert your CPAP SD card
# Find the mount point (usually /Volumes/something)

# Sync data to local storage
cpap-sync /Volumes/CPAP_CARD ~/cpap-data

# You can run this weekly/monthly to update data
cpap-sync /Volumes/CPAP_CARD  # Uses ~/cpap-data by default

Step 3: Configure Claude Code CLI

Add the MCP server to your Claude Code configuration:

macOS: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "cpap-analyst": {
      "command": "/Users/YOUR_USERNAME/CPAP-analyst-MCP/venv/bin/python",
      "args": [
        "-m",
        "cpap_analyst.mcp.server"
      ],
      "env": {
        "CPAP_DATA_DIR": "/Users/YOUR_USERNAME/cpap-data"
      }
    }
  }
}

Replace YOUR_USERNAME with your actual username!

Step 4: Restart Claude Code

Restart Claude Code to load the MCP server.

Usage

Once installed, you can ask Claude natural language questions about your CPAP therapy:

Example Queries

Recent sessions:

"Show me my CPAP sessions from the last 7 days"

Specific night:

"What happened on 2025-01-15? Show me the details"

Therapy assessment:

"Should I continue with CPAP treatment? Give me an honest assessment"

Problem detection:

"Which nights had high leaks or AHI problems?"

Trends:

"How has my AHI changed over the last month?"

Available MCP Tools

The server exposes 4 tools that Claude can use:

1. get_recent_sessions

View recent therapy sessions (default: last 7 days).

Parameters:

  • days (int, optional): Number of days to look back

Output: Table of sessions with AHI, leak rates, pressure, compliance

2. get_session_details

Get detailed breakdown of a specific night.

Parameters:

  • date (string, required): Date in YYYY-MM-DD format

Output: Full event timeline, pressure stats, leak analysis

3. get_therapy_summary

Aggregate statistics and effectiveness assessment.

Parameters:

  • start_date (string, optional): Start date filter
  • end_date (string, optional): End date filter

Output:

  • Average AHI, compliance %, usage hours
  • Leak statistics
  • Effectiveness score (0-100)
  • Recommendation (continue/adjust/consult)

4. list_problem_sessions

Find sessions with high AHI or leak issues.

Parameters:

  • ahi_threshold (float, optional): Default 5.0
  • leak_threshold (float, optional): Default 24.0 L/min

Output: Filtered list of problematic sessions

Understanding the Metrics

AHI (Apnea-Hypopnea Index)

Formula: (Obstructive Apneas + Apneas + Hypopneas) / Hours

Interpretation:

  • < 5: Normal/Mild (therapy working well)
  • 5-15: Moderate (may need pressure adjustment)
  • > 15: Severe (pressure settings likely inadequate)

Leak Rate

Threshold: 24 L/min

  • Below 24 L/min: Normal
  • Above 24 L/min: High leak - check mask fit

High leaks invalidate event detection. If you have frequent high leaks, the machine can't accurately measure apneas.

Compliance

Goal: ≥ 4 hours/night for 70% of nights

  • 4+ hours: Compliant session ✓
  • < 4 hours: Non-compliant ✗

Insurance typically requires 70% compliance over 30 days.

Pressure Settings

Measured in cmH₂O (centimeters of water pressure).

  • Median pressure: Middle pressure during the night
  • 95th percentile: Peak pressure used
  • Range: Min to max pressure

If AHI is high but pressure is at max, you may need higher pressure settings.

Syncing Data

Manual Sync

# Basic sync
cpap-sync /Volumes/CPAP_CARD

# Custom destination
cpap-sync /Volumes/CPAP_CARD ~/my-cpap-data

# Force overwrite existing files
cpap-sync /Volumes/CPAP_CARD --force

# Skip verification (faster)
cpap-sync /Volumes/CPAP_CARD --no-verify

Sync Frequency

  • Weekly: Recommended for active therapy monitoring
  • Monthly: Fine for long-term trends
  • After changes: Always sync after pressure adjustments or mask changes

Troubleshooting

"No CPAP data found"

  1. Check that you've synced data: cpap-sync /Volumes/CPAP_CARD
  2. Verify files exist: ls ~/cpap-data/*.tdf
  3. Check CPAP_DATA_DIR in Claude Code config matches your data location

"No TDF files found on SD card"

  1. Ensure SD card is properly mounted
  2. Check for WM_DATA.TDF file: find /Volumes -name "*.tdf" 2>/dev/null
  3. Try different mount point (some systems use /media or /mnt)

"Failed to parse session"

Some TDF files may have formatting issues. The parser will:

  • Skip problematic sessions
  • Log warnings
  • Continue processing other sessions

MCP Server Not Showing in Claude

  1. Verify config file location: ~/.config/claude/claude_desktop_config.json
  2. Check Python path is correct: which python (inside venv)
  3. Restart Claude Code completely
  4. Check Claude Code logs for errors

Development

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

Architecture

See for detailed technical documentation.

Key components:

  • parsers/weinmann.py: TDF format parser
  • models/session.py: Data models
  • models/metrics.py: AHI, leak, compliance calculations
  • mcp/server.py: MCP server with tools
  • sync/sdcard.py: SD card sync utility

Clinical Reference

CPAP therapy is effective if:

  1. AHI trending down over weeks
  2. Consistent usage (≥ 4 hrs/night)
  3. Low leak rates (< 24 L/min)
  4. Pressure within therapeutic range

Red flags (consult provider):

  1. AHI not improving after 2+ weeks
  2. Persistent high leaks despite mask adjustments
  3. Pressure maxing out but AHI still high
  4. Side effects (aerophagia, skin irritation)

This tool does NOT replace medical advice. Use it to have informed discussions with your sleep medicine provider.

Resources

OSCAR Software

This parser is based on format understanding from OSCAR (Open Source CPAP Analysis Reporter):

Use both tools together:

  • CPAP Analyst MCP: Natural language queries via Claude
  • OSCAR: Visual analysis, waveforms, trends graphs

Educational Videos

License

GPL-3.0

Attribution: This software is based on format understanding from OSCAR (Open Source CPAP Analysis Reporter), which is free and open-source software licensed under GPL-3.0.

Contributing

Issues and pull requests welcome! See the GitHub repository.

Disclaimer

This is not medical software. CPAP Analyst MCP is a data analysis tool for personal use. It does not diagnose, treat, or provide medical advice. Always consult with a qualified sleep medicine physician for therapy decisions.

Support

For issues or questions:

Built for Joc - Making CPAP therapy data accessible through Claude Code.