Quantified Self MCP Server
by Thecimal
README.md
# Quantified Self MCP
[](https://github.com/Thecimal/quantified-self-mcp/actions)
[](https://pypi.org/project/quantified-self-mcp/)
[](https://github.com/Thecimal/quantified-self-mcp/blob/main/LICENSE)
[](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
See the [import documentation](docs/).
---
## 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/) 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
```
### 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/)**
- **[Tool reference](docs/)**
- **[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
Every tool carries explicit 'use this when' and 'do not use this when' guidance that routes overlapping analytics tools to one another, so the boundaries between get_baseline, detect_metric_anomalies, calculate_metric_trend, compare_metric_periods, get_recent_changes, and explain_metric_change are unambiguous. Read paths (read_health_data vs get_metric_history vs read_measurements) and write paths (log_measurement vs log_daily_metric vs log_workout_session) are similarly well-separated.
Naming Consistency5/5
All 20 tools use lower_snake_case with a clear verb_noun shape (get_*, read_*, log_*, calculate_*, detect_*, compare_*, find_*, export_*, clear_*), plus one consistent naming of the aggregate. There are no camelCase/naming aberrations or vague single-word verbs, so the pattern is highly predictable.
Tool Count4/5
At 20 tools this is on the heavier end, but the domain genuinely spans raw observations, daily aggregates, workouts, imports, exports, and a layered analytics stack, and each tool earns its place. It sits just below the 'heavy' 16-25 range boundary, so it is slightly over but reasonable.
Completeness4/5
The surface covers ingestion (raw and daily), clearing/undo, multi-source provenance, freshness and import monitoring, CSV export, and a full analytics suite, which is near-complete for a quantified-self domain. Minor gaps exist, such as no explicit update/edit for an already-logged workout session (only day-level clear_metric), which an agent can work around.
Maintenance
ActivityActive
ResponsivenessResponsive