quantified self MCP

---

⚡ Instant Client Setup

Connect Quantified Self MCP to your favorite AI assistant in seconds:

Claude Desktop

Add this to your Claude Desktop configuration:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "quantified-self": {
      "command": "uvx",
      "args": ["quantified-self-mcp"]
    }
  }
}

(Or point "command" to your installed quantified-self-mcp binary if installed via pip).

Cursor

In Cursor, navigate to Settings → Features → MCP Servers → Add New MCP Server, or add to .cursor/mcp.json:

{
  "mcpServers": {
    "quantified-self": {
      "command": "uvx",
      "args": ["quantified-self-mcp"]
    }
  }
}

Windsurf

Add to your mcp_config.json:

{
  "mcpServers": {
    "quantified-self": {
      "command": "uvx",
      "args": ["quantified-self-mcp"]
    }
  }
}

[!TIP] Need guides for LM Studio, Open WebUI, or Android Health Connect? See our step-by-step Client Guides.

---

🚀 Quick Start

1. Install

pip install quantified-self-mcp

2. Initialize (Try in 10 Seconds with Demo Data)

Quantified Self MCP automatically creates and manages a local SQLite database (health.db). You can test it immediately with 60 days of realistic sample data, or import your personal health history:

# Instant demo mode (seeds 60 days of synthetic health data):
quantified-self-init-db --demo

# Or import your own wearable exports:
quantified-self-init-db export.xml                # Apple Health
quantified-self-init-db whoop.json --source whoop # WHOOP Developer API (v2)
quantified-self-init-db oura.json --source oura   # Oura Ring API (v2)
quantified-self-init-db health_connect_export.zip # Android Health Connect
quantified-self-init-db your-health-data.csv      # CSV

3. Verify Setup

Run the built-in diagnostic tool to verify Python dependencies, schema integrity, and database readiness:

quantified-self-doctor

4. Ask Your AI

Open your MCP-connected assistant and ask questions in plain English:

"How has my sleep and resting heart rate changed over the last 30 days?"
"Why did my HRV drop last week?"
"What patterns exist between my workout minutes and sleep quality?"
"Which of my health metrics changed the most this month?"

---

💡 Why Quantified Self MCP?

Most health apps either trap your data in a closed cloud dashboard or feed raw numbers blindly into an LLM. Quantified Self MCP provides a trustworthy, analytical bridge:

Feature	Standard Health Dashboards	Naive LLM Prompts	Quantified Self MCP
Data Ownership	❌ Locked in Cloud	⚠️ Uploaded to 3rd-party	✅ 100% Local SQLite
Privacy Redaction	❌ All or nothing	❌ Raw data dumped	✅ Granular Field Exclusion
Statistical Claims	⚠️ Uncalibrated percentages	❌ Hallucinated correlations	✅ ClaimEvidence & Caveats
Provenance Tracking	❌ Opaque	❌ None	✅ Multi-source origin stamps
Atomic Snapshots	⚠️ Manual exports	❌ None	✅ WAL-safe backup/restore

🔒 100% Local & Private

Your database lives on your machine in SQLite. No proprietary health cloud required. If you want a completely offline, air-gapped system, pair it with local models via LM Studio or Ollama.

You can also redact specific sensitive metrics from being exposed to the AI:

export HEALTH_PRIVATE_FIELDS=weight_kg,mood

Private fields remain safely stored in SQLite for your own records, but are blocked from all AI queries and analytics.

---

🔎 Evidence & Provenance Engine

When an AI analyzes your health, a number without context is dangerous.

If an LLM sees a 24% drop in HRV, did it come from 30 continuous days of wearable data, or just 4 sparse readings with a week-long gap?

Quantified Self MCP solves this with an integrated ClaimEvidence Engine:

Analysis Result
     ↓
claim: ClaimEvidence
     ├── evidence   → Raw coverage observed (days logged, max gap, freshness)
     ├── profile    → Dimension assessment (sample size, temporal span, missingness)
     └── decision   → Authoritative claim tier:
                      [ insufficient | suggestive | detectable_not_meaningful | supported ]
                      + specific mandatory caveats (must_state)

Example: Naive vs. Evidence-Backed AI Response

• Without Evidence Engine (Naive LLM):

  "Your HRV dropped 24% over the last month. You may be overtraining."

• With Quantified Self MCP Evidence:

  "Your HRV decreased 24% over the last 30 days — but HRV was only logged on 71% of those days with a 5-day recording gap, so this is flagged as suggestive rather than a confirmed trend. (Source: Apple Watch)."

Every analytical tool (calculate_metric_trend, explain_metric_change, detect_metric_anomalies) returns explicit claim tiers alongside mandatory disclosures.

---

📊 Supported Data & Integrations

Quantified Self MCP ships with 20 specialized tools spanning raw measurements, longitudinal statistics, and data health:

                  AI Agent (Claude / Cursor / LM Studio)
                                   │
                              MCP Protocol
                                   │
                                   ▼
          ┌──────────────────────────────────────────────────┐
          │               Quantified Self MCP                │
          │                                                  │
          │  • Data Access         • Longitudinal Analytics  │
          │  • Workout Tracking    • ClaimEvidence Engine    │
          │  • Provenance Resolver • Data Freshness/Health   │
          └────────────────────────┬─────────────────────────┘
                                   │
                                   ▼
                         Local SQLite (health.db)

Metrics Supported Out of the Box

Metric	Category	Standard Unit	Notes
👟 Steps	Activity	count	Summed per day with multi-source deduplication
😴 Sleep	Recovery	hours	Provenance-checked interval handling
❤️ Resting Heart Rate	Cardiovascular	bpm	Daily baseline tracking & anomaly detection
📈 HRV (Heart Rate Variability)	Recovery	ms	RMSSD/SDNN normalized
⚖️ Weight & Body Fat	Measurements	kg / %	High-precision episodic measurement tracking
🏋️ Workouts	Activity	minutes / kcal	Individual workout sessions with sport metadata
🙂 Mood	Wellness	1-5 scale	Subjective well-being logs
💧 Water Intake	Nutrition	ml	Daily fluid tracking

The schema is fully extensible with custom metric definitions in metric_registry.py.

---

🔌 Client Compatibility

Client / Assistant	Compatibility	Documentation
Claude Desktop	✅ Official Support	Claude Desktop Setup Guide
Cursor	✅ Full Support	Cursor IDE Setup Guide
Windsurf	✅ Full Support	Configure via mcp_config.json
LM Studio	✅ Local AI	LM Studio Setup Guide
Open WebUI	✅ Self-Hosted	Open WebUI Setup Guide
Android Health Connect	✅ Export & Ingest	Health Connect Guide

---

🛠️ Operations & Data Safety

Atomic WAL Backups

Never copy health.db while your server or MCP client is running: SQLite runs in WAL mode, meaning uncommitted writes live in health.db-wal.

Use the built-in backup CLI, which takes a live, consistent snapshot:

# Create a verified snapshot:
quantified-self-backup create ~/backups/health-2026-11-04.db

# Safe restore (checks schema integrity before moving old DB aside):
quantified-self-backup restore ~/backups/health-2026-11-04.db

Diagnostics

Run anytime to check your Python runtime, database version, and environment configuration:

quantified-self-doctor

---

📚 Documentation

Deep-dive documentation and technical specs:

• Complete Tool Catalog (20 Tools)
• Data Import Guide (Apple Health, WHOOP, CSV)
• Client Setup Guides
• Security & Threat Model
• Contribution Guidelines
• Changelog

---

🤝 Contributing

Contributions are warmly welcomed! We are actively looking for contributions in:

• New wearable & app adapters (Garmin, Oura, Fitbit)
• Specialized analytical & correlation tools
• Evidence engine calibration
• New MCP client integrations

Please review CONTRIBUTING.md and CODE_OF_CONDUCT.md before opening a pull request.

---

📄 License

Licensed under the MIT License.