Quantified Self MCP

Your health data. Your AI. Your machine.

Quantified Self MCP is a privacy-first Model Context Protocol (MCP) server that gives AI agents controlled access to your personal health data stored locally.

Built with Python, FastMCP, and SQLite, it works with both local LLMs and cloud-based LLMs. You choose where your AI runs.

Try it on Glama →

---

What Is It?

Quantified Self MCP connects an AI agent to your personal health data through the Model Context Protocol (MCP).

                 ┌─────────────────────┐
                 │      AI Agent       │
                 │                     │
                 │ Local LLM / Cloud   │
                 └──────────▲──────────┘
                            │
                     MCP tool result
                            │
                     MCP tool call
                            │
                 ┌──────────┴──────────┐
                 │ Quantified Self MCP │
                 │      FastMCP        │
                 │       LOCAL         │
                 └──────────▲──────────┘
                            │
                       SQL / data
                            │
                 ┌──────────┴──────────┐
                 │    Local SQLite     │
                 │     Health Data     │
                 │       LOCAL         │
                 └─────────────────────┘

The MCP server does not require a specific AI provider.

You can run the entire AI stack locally, or connect the server to an online model when you prefer.

---

🏠 Local AI or ☁️ Cloud AI

The important distinction is between the MCP server and the AI model.

Fully Local

Your Health Data
       ↓
Local SQLite
       ↓
Quantified Self MCP
       ↓
Local AI Agent
       ↓
Local LLM

With a local MCP-compatible agent and local LLM, your health data and AI inference can remain on your machine.

Cloud LLM

Your Health Data
       ↓
Local SQLite
       ↓
Quantified Self MCP
       ↓
AI Agent
       ↓
Cloud LLM

You can also connect the same MCP server to a hosted model.

In that setup, your database and MCP server remain local, while data returned by MCP tools may be sent to the cloud model provider.

The choice is yours.

Quantified Self MCP does not lock you into Claude, OpenAI, or any other model provider.

---

🔒 Privacy First

Your health data is stored locally in SQLite, and the MCP server runs on your machine.

The server itself does not require a cloud database, account, or hosted data store.

For maximum privacy, use a local LLM so the entire pipeline can remain on your machine.

┌───────────────────────────────────┐
│          YOUR MACHINE             │
│                                   │
│          Health Data              │
│               ↓                   │
│          Local SQLite             │
│               ↓                   │
│      Quantified Self MCP          │
│               ↓                   │
│         Local AI Agent            │
│               ↓                   │
│           Local LLM               │
│                                   │
└───────────────────────────────────┘

Optional Private Fields

If specific metrics should never be returned to the model, configure:

HEALTH_PRIVATE_FIELDS=weight_kg,mood

Private fields can still be stored and logged, but MCP read operations return them as null.

This gives you another layer of control over which health metrics an AI agent can access.

---

❤️ What Can It Track?

Quantified Self MCP currently supports:

• 👟 Daily steps
• 😴 Sleep duration
• ❤️ Resting heart rate
• ❤️ Heart rate
• 📈 Heart-rate variability (HRV)
• ⚖️ Weight
• 🏋️ Workout minutes
• 🙂 Mood
• 💧 Water intake

Every metric is optional, so you can track only the measurements you actually use.

---

💬 What Can You Ask?

Once connected to an MCP-compatible AI agent, you can ask questions naturally.

For example:

How has my sleep changed over the last 30 days?

What was my average step count this week?

Show me my resting heart rate trend.

How much water did I drink on average this month?

What patterns do you see in my recent health data?

You can also log information through the AI agent:

Log 7.5 hours of sleep for today.

Or correct a mistake:

Clear today's mood entry.

---

🧠 MCP Tools

The server exposes thirteen MCP tools, organized in three layers:

Layer 1 — Data

Tool	Purpose
read_health_data	Read all health metrics for a selected date range
get_metric_history	Read a single metric's day-by-day values for a date range
log_daily_metric	Record one or more health metrics for a specific day
clear_metric	Clear a single metric without affecting other data
export_health_data_csv	Write a date range of metrics to a local CSV file
get_metric_provenance	Retrieve provenance information for a health metric and its source data

export_health_data_csv writes straight to disk next to the database and returns only the file's path and a row count — not the row values themselves — so exporting a long history doesn't have to pass through a cloud LLM's context just to get a file you can open elsewhere.

Layer 2 — Analytics (statistics computed over one or two metrics; see analytics.py)

Tool	Purpose
get_baseline	Mean/median/stdev for a metric over a window — "what's normal"
detect_metric_anomalies	Flag days that deviate sharply from a metric's own baseline
calculate_metric_trend	Fit a straight-line trend (direction, slope, r²) over a window
compare_metric_periods	Compare a metric's average between two date ranges
find_metric_correlation	Pearson correlation between two metrics, with optional lag

Layer 3 — Personal intelligence (composes Layer 2, returns facts rather than prose — the calling model still does the narration)

Tool	Purpose
get_recent_changes	Scan every metric for notable shifts, anomalies, or trends recently
explain_metric_change	Build an evidence bundle for "why did X look like that on this day?"

The server also exposes read-only MCP resources for health metric schemas and individual days.

All data operations are scoped to the supported health metrics. The server does not expose arbitrary SQL execution to the model. Any metric listed in HEALTH_PRIVATE_FIELDS is refused by every Layer 2/3 tool outright (not just redacted afterward), since a baseline or anomaly computed from a private metric would leak its shape even without ever printing a raw value.

---

📚 Documentation Source of Truth

The MCP server implementation is the authoritative source for its available tools and schemas.

Because MCP clients and directories such as Glama inspect the running server directly, manually maintained tool lists can become outdated as new tools and metrics are added.

The project therefore treats the registered MCP tools and their schemas as the source of truth for tool documentation.

Tool documentation should be generated from the server's registered tools rather than maintained independently wherever practical.

A documentation check should ensure that:

MCP Server
    ↓
Registered Tools
    ↓
Generated Documentation
    ↓
README / TOOLS.md

remain synchronized.

This prevents discrepancies between:

Actual implementation
        ≠
GitHub documentation
        ≠
MCP directory inspection

and makes the available MCP interface easier for users, contributors, AI agents, and MCP directories to understand.

---

📥 Import Your Health Data

You can initialize the local database from CSV data.

quantified-self-init-db sample_data/health_sample.csv

The supported health fields include:

date
steps
sleep_hours
resting_heart_rate
heart_rate
hrv_ms
weight_kg
workout_minutes
mood
water_ml

You can also import an Apple Health export:

quantified-self-init-db export.xml

The importer maps supported Apple Health records into the local database.

---

⚡ Installation

PyPI

pip install quantified-self-mcp

This installs:

quantified-self-mcp
quantified-self-init-db

From Source

git clone https://github.com/Thecimal/quantified-self-mcp.git
cd quantified-self-mcp

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

Docker

docker build -t quantified-self-mcp .

The included Docker configuration can be used for containerized MCP deployments, including Glama.

---

🚀 Quick Start

1. Install

pip install quantified-self-mcp

2. Load your health data

quantified-self-init-db your-health-data.csv

3. Connect the MCP server

Connect Quantified Self MCP to an MCP-compatible AI agent.

4. Choose your model

Use either:

• A local LLM
• A cloud-based LLM

5. Ask your health data questions

How has my sleep changed over the last 30 days?

The AI agent retrieves the relevant health data through MCP and analyzes it.

---

🔌 MCP Client Compatibility

Quantified Self MCP uses the standard Model Context Protocol, so the server is designed to work with MCP-compatible clients and models rather than being tied to a single AI application.

The project includes configuration for clients supported by FastMCP, and standard MCP configuration can be generated for other compatible clients.

For local AI setups, pair the server with an MCP-compatible client and a local LLM runtime.

For example:

Local LLM
   +
MCP-compatible Agent
   +
Quantified Self MCP

This allows the complete AI workflow to remain local.

---

🏗️ Architecture

                         ┌────────────────────┐
                         │      AI Agent      │
                         └─────────┬──────────┘
                                   │
                              MCP Protocol
                                   │
                                   ▼
                         ┌────────────────────┐
                         │ Quantified Self    │
                         │       MCP          │
                         │                    │
                         │      FastMCP       │
                         └─────────┬──────────┘
                                   │
                                   ▼
                         ┌────────────────────┐
                         │    Local SQLite    │
                         │                    │
                         │    Health Data     │
                         └────────────────────┘

The AI model and the MCP server are separate components.

This means you can change the AI model without changing how your health data is stored or exposed.

---

🛠️ Technology

Component	Technology
Language	Python
Protocol	Model Context Protocol
MCP Framework	FastMCP
Database	SQLite
Containerization	Docker
CI	GitHub Actions
Package	PyPI

---

🧪 Development

Clone the repository:

git clone https://github.com/Thecimal/quantified-self-mcp.git
cd quantified-self-mcp

Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install dependencies:

pip install -r requirements-dev.txt

Run tests:

pytest

Build the package:

python -m build

GitHub Actions validates the project in a clean environment.

---

📁 Project Structure

quantified-self-mcp/
├── .github/
│   └── workflows/
├── sample_data/
├── tests/
├── Dockerfile
├── fastmcp.json
├── glama.json
├── init_db.py
├── logic.py
├── import_adapters.py
├── server.py
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
├── SECURITY.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── CHANGELOG.md
├── llms.txt
├── LICENSE
└── README.md

---

🛡️ Security

Health information is sensitive personal data.

Never commit:

• Personal health records
• Private SQLite databases
• API keys
• Passwords
• Authentication tokens
• Other sensitive personal information

For security vulnerabilities, please follow the instructions in SECURITY.md.

---

⭐ Glama

Quantified Self MCP is available through the Glama MCP directory.

Glama Score

A / A / A

Category	Score
License	A
Quality	A
Maintenance	A

The project is listed as a Python / Local MCP server on Glama. Glama performs its own inspection of the MCP server and may expose the current registered tools and schemas directly.

Because the server implementation is the source of truth, the Glama inspection may reflect newly registered tools or metrics before corresponding manually written documentation has been updated.

View Quantified Self MCP on Glama →

---

🤝 Contributing

Contributions, bug reports, documentation improvements, and ideas are welcome.

Before contributing, please read:

• CONTRIBUTING.md
• SECURITY.md

If you find a bug, please open an issue with enough information to reproduce it.

---

📄 License

MIT License.

---

Links

• GitHub: https://github.com/Thecimal/quantified-self-mcp
• PyPI: https://pypi.org/project/quantified-self-mcp/
• Glama: https://glama.ai/mcp/servers/Thecimal/quantified-self-mcp
• Author: https://github.com/Thecimal

---

Quantified Self MCP

Your health data. Your AI. Your machine.