Quantified Self MCP Server
by Thecimal
README.md
# Quantified Self MCP
[](https://github.com/Thecimal/quantified-self-mcp/actions)
[](https://github.com/Thecimal/quantified-self-mcp/actions/workflows/codeql.yml)
[](https://pypi.org/project/quantified-self-mcp/)
[](https://pypi.org/project/quantified-self-mcp/)
[](https://github.com/Thecimal/quantified-self-mcp/blob/main/LICENSE)
[](https://github.com/astral-sh/ruff)
[](https://github.com/pre-commit/pre-commit)
[](https://m8ven.ai/mcp/thecimal-quantified-self-mcp-v6tlvp)
[](https://glama.ai/mcp/servers/Thecimal/quantified-self-mcp)
<img width="1536" height="1024" alt="bd0ee6dc-c3e0-4c7d-8bc7-17de569e1cb5" src="https://github.com/user-attachments/assets/447e8018-b56f-4dfb-bfa9-909e9ad0de6f" />
> **Your health data. Your AI. Your machine.**
>
> A local-first MCP server that gives AI agents access to your personal health data — with **privacy, provenance, and evidence built in**.
· **[Documentation](docs/)**
---
## What is it?
Quantified Self MCP gives an AI agent a **local, structured interface to your own health history**.
Instead of another health dashboard, you can ask your AI questions like:
```text
Why did my HRV change recently?
How has my sleep changed over the last 30 days?
What happened to my resting heart rate after my workouts increased?
What patterns do you see across my recent health data?
Which metrics changed the most this month?
```
The AI retrieves the relevant data through MCP and analyzes it.
> **The goal isn't another health dashboard.**
>
> **It's a trustworthy interface between your health history and your AI.**
---
## Why is it different?
### 🔒 Local-first
Your health database runs locally in SQLite.
You control where your data goes.
You can use a completely local AI stack:
```text
Health Data
↓
Local SQLite
↓
Quantified Self MCP
↓
MCP Agent
↓
Local LLM
```
Cloud models are also supported. In that configuration, the MCP database remains local, but data returned by MCP tools may be sent to the model provider.
### 🤖 AI-native
Built specifically for **MCP-compatible AI agents**, rather than another standalone health application.
### 🔎 Evidence & provenance
Analytics can be traced back to the underlying health data and its provenance.
The goal is not simply:
```text
HRV ↓ 24%
```
but understanding:
```text
What data produced this result?
Where did it come from?
What period was analyzed?
How strong is the evidence, and how strongly may it be claimed?
```
Concretely, every trend, baseline, anomaly, comparison, correlation, recent change, and explained metric carries a `claim` alongside its numbers — not just descriptive coverage, but an explicit, machine-checkable statement of how strongly the result may be reported:
```text
Analysis result
↓
claim: ClaimEvidence
├── evidence → what data was actually observed (coverage, gaps, freshness)
├── profile → how much evaluative evidence exists, per dimension
│ (sample, temporal, missingness, ...)
└── decision → what claim strength is justified: insufficient,
suggestive, detectable_not_meaningful, or supported —
plus the specific caveats that must be stated
```
`evidence` is descriptive: it reports the coverage a result rests on (how many days were logged, how large any gaps are, how fresh the data is). `profile` evaluates that coverage along several independent dimensions rather than collapsing it into one number. `decision` is the authoritative output: the only field that says how strongly the result may actually be claimed, and it is derived exclusively from the assessed dimensions in `profile` — never from a raw coverage number by itself. Composite results (like explaining a metric change, which combines a headline claim, a trend claim, and any correlations) roll their component decisions up into a single `overall_decision`, which is never stronger than the weakest component.
**Without evidence:**
> Your HRV decreased 24% over the last 30 days.
**With evidence:**
> Your HRV decreased 24% over the last 30 days — but HRV was only logged on 71% of those days, so treat this trend cautiously rather than as a settled pattern.
The second answer is what `calculate_metric_trend` (and every other analytics tool) is designed to make possible: the tool returns the 24% figure *and* a `claim.decision` alongside it (e.g. `tier: "suggestive"`, with `must_state` naming the specific gaps and low-coverage days behind that tier), and each tool's own description tells the calling model to report that tier and those caveats rather than stating the number as if it came from a complete series.
### 📊 Longitudinal
Analyze health history across days, weeks, months, and years:
- trends
- baselines
- anomalies
- period comparisons
- correlations
- recent changes
- metric explanations
### 📥 Import existing data
Bring your existing health history into the local database.
Supported imports include:
- CSV
- Apple Health exports
- WHOOP Developer API JSON (v2)
See the [import documentation](docs/importing.md).
---
## What can your AI do?
### Read
- Health metrics
- Metric history
- Raw measurements
- Workout sessions
- Data provenance
### Analyze
- Baselines
- Trends
- Anomalies
- Period comparisons
- Correlations
### Explain
- Recent changes
- Metric changes
- Supporting evidence
- Data provenance
The MCP currently exposes **20 tools** across data access, measurements, workouts, analytics, personal intelligence, and data freshness (`get_data_status`, `get_import_status`).
See the [tool reference](docs/tools.md) for the complete list.
---
## Supported data
Currently supported metrics include:
- 👟 Steps
- 😴 Sleep
- ❤️ Heart rate
- ❤️ Resting heart rate
- 📈 HRV
- ⚖️ Weight
- 🏋️ Workout minutes
- 🙂 Mood
- 💧 Water
The data model is extensible, so you can keep only the metrics you actually use.
---
## Quick start
### Install
```bash
pip install quantified-self-mcp
```
### Import your data
CSV:
```bash
quantified-self-init-db your-health-data.csv
```
Apple Health:
```bash
quantified-self-init-db export.xml
```
Android Health Connect:
```bash
quantified-self-init-db health_connect_export.zip
```
WHOOP Developer API (v2) JSON:
```bash
quantified-self-init-db whoop.json --source whoop
```
### Verify your setup (optional)
Run the built-in diagnostic tool to check Python, dependencies, and database readiness:
```bash
quantified-self-doctor
```
### Back up and restore your data
Do not back up by copying `health.db`: the database runs in WAL mode, so recent changes can still be in
`health.db-wal`, and a copy of `health.db` alone can be empty or out of date. Use the backup command, which
takes a consistent snapshot even while your MCP client is running:
```bash
quantified-self-backup create ~/backups/health-2026-10-21.db
```
It never overwrites an existing backup. To restore (close your MCP client first), run:
```bash
quantified-self-backup restore ~/backups/health-2026-10-21.db
```
The backup is checked before anything is touched (it must pass SQLite's integrity check, be a health database,
and not come from a newer release). Your current database is moved aside as `health.db.pre-restore-<time>`
rather than deleted. If the database is encrypted (`HEALTH_DB_PASSPHRASE`), the backup is encrypted with the
same passphrase. Use `--db-path` to point at a database other than the default.
### Connect an MCP client
Configure your preferred MCP-compatible client to run:
```bash
quantified-self-mcp
```
Client-specific setup guides are available in [`docs/clients/`](docs/clients/).
### Ask your AI
```text
How has my sleep changed over the last 30 days?
```
That's it.
---
## Privacy
Health data is sensitive.
Quantified Self MCP is designed around **local ownership**:
- Your database stays on your machine.
- No proprietary health-data cloud is required.
- You choose the AI model.
- You can run the entire stack locally.
- Private metrics can be excluded from AI access.
For example:
```bash
HEALTH_PRIVATE_FIELDS=weight_kg,mood
```
Private fields remain stored locally but are excluded from MCP read and analytical operations.
See [`SECURITY.md`](SECURITY.md) for security considerations.
---
## Architecture
```text
AI Agent
│
MCP Protocol
│
▼
┌─────────────────────┐
│ Quantified Self MCP │
│ │
│ Data · Analytics │
│ Evidence │
└──────────┬──────────┘
│
▼
Local SQLite
│
▼
Your Health Data
```
The MCP server is the bridge between your health history and your AI.
---
## Documentation
Detailed documentation lives outside the README:
- **[Client setup](docs/clients/)**
- **[Importing health data](docs/importing.md)**
- **[Tool reference](docs/tools.md)**
- **[Security](SECURITY.md)**
- **[Contributing](CONTRIBUTING.md)**
- **[Changelog](CHANGELOG.md)**
---
## Open source
Quantified Self MCP is open source and built for the wider MCP ecosystem.
Contributions are welcome — especially around:
- health-data imports
- analytics
- evidence and data quality
- privacy
- MCP client integrations
- documentation
See [`CONTRIBUTING.md`](CONTRIBUTING.md).
---
## License
MIT
---
> **Your health data. Your AI. Your machine.**
>
> **Local data. Open protocol. AI-powered insight.**
TDQS
A4.4/5.0
Scored across 20 tools
Disambiguation5/5
Each tool has an explicit 'use this when / do not use this when' section that routes the agent to the correct alternative, and the overlapping candidates (read_health_data vs get_metric_history vs read_measurements, get_baseline vs calculate_metric_trend vs detect_metric_anomalies) are cleanly distinguished by scope. The read/write/log/aggregate/analytics split is unambiguous even for an agent scanning names alone.
Naming Consistency4/5
All names are snake_case verb_noun, but read-only tools mix 'read_*' (read_health_data, read_measurements) and 'get_*' (get_metric_history, get_baseline) with no clear rule distinguishing them, and some names append _csv or use long sub-verbs. Still predictable and readable, just not perfectly uniform.
Tool Count4/5
20 tools is on the heavy side, but the domain genuinely spans raw/aggregate reads, two logging paths, workout sessions, provenance, status/imports, and seven distinct analytics operations. Each tool covers a distinct capability rather than padding, so the count is justified, if slightly large.
Completeness4/5
The surface covers read/aggregate/log/clear for metrics plus workouts, provenance, data/import status, CSV export, and a full analytics suite (baseline, anomaly, trend, period compare, correlation, recent changes, explain). Minor gaps remain: no update/delete for individual measurements or workout sessions beyond clear_metric for daily metrics.
Maintenance
ActivityActive
ResponsivenessResponsive