Wellness Planner
Provides tools to query personal health data stored in a SQLite database, allowing AI agents to perform aggregated health summaries and execute raw SQL queries for detailed data analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Wellness Planner Generate an energy-aware schedule for my tasks today."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Wellness Planner
A local MCP agent that queries personal health data and provides energy-aware task scheduling.
Data Note
This project uses simulated data. Health data is seeded from data/seed_db.py into a SQLite database. There is no Apple Health integration — real health data is not imported or synced.
Related MCP server: Productivity Tracker MCP Server
Running the Code
Prerequisites
Python 3.14+
uv for dependency management
Standalone Agent (no MCP server required)
Run the Plan-and-Execute agent loop locally:
uv run python mcp_server/agent.py [YYYY-MM-DD]Uses yesterday's date if no date is given.
Reads from
data/health.dbanddata/todo.json.Prints a daily brief: sleep, activity, heart rate, readiness score, and proposed schedule.
MCP Server (for Cursor)
The MCP server is spawned by Cursor when needed — you do not start it manually in a separate terminal.
Configure Cursor to use the local MCP server (e.g.
.cursor/mcp.json):
{
"mcpServers": {
"wellness-planner": {
"command": "uv",
"args": ["run", "--directory", "/path/to/wellness_planner", "python", "mcp_server/server.py"]
}
}
}Replace
/path/to/wellness_plannerwith your actual project path.Cursor will spawn the server and communicate over stdio.
Other Commands
Command | Purpose |
| Placeholder entry point |
| Seed |
MCP Tools
When the server is connected, these tools are available:
get_health_summary— Aggregated sleep, activity, and heart rate for a datecalculate_readiness_score— 1–10 readiness score for task timingquery_raw_logs— Run read-only SQL against the health DBget_tasks— Load tasks fromtodo.jsonpropose_schedule— Energy-aware schedule based on readiness and tasksget_data_dictionary— Schema introspection: column names, types, and sample valuesrun_analysis— Execute a pandas/sqlite analysis script locally; returns stdoutgenerate_chart— Produce a self-contained Observable Plot HTML chartget_insights— Retrieve previously saved findings from the Fact Storesave_insight— Persist a discovered insight so it isn't re-computed next session
Testing
There are two layers to test: the skills directly, and the MCP tools through Cursor chat.
1. Test skills directly (fast, no Cursor needed)
Phase 1 — Sandbox execution:
uv run python -c "
from skills.sandbox import run_python_analysis
r = run_python_analysis('''
df = pd.read_sql('SELECT date, total_hours FROM sleep_logs ORDER BY date DESC LIMIT 7', __import__('sqlite3').connect(DB_PATH))
print(df.to_string(index=False))
''')
print(r['output'])
"Phase 2 — Schema discovery:
uv run python -c "
from skills.schema import get_data_dictionary
import json
print(json.dumps(get_data_dictionary(), indent=2))
"Phase 3 — Chart generation:
uv run python -c "
import sqlite3
from skills.visualization import generate_chart
rows = sqlite3.connect('data/health.db').execute('SELECT date, total_hours FROM sleep_logs ORDER BY date').fetchall()
r = generate_chart([{'date': r[0], 'total_hours': r[1]} for r in rows], 'Sleep Trend', 'date', 'total_hours')
print(r)
"Then open the url value in a browser to see the chart.
Phase 4 — Fact Store:
uv run python -c "
from skills.memory import save_insight, get_insights, clear_insights
save_insight('test_key', 'test value', 'manual test')
print(get_insights())
clear_insights()
"2. Test end-to-end through Cursor (the real agentic loop)
Ask the agent questions in chat and watch the MCP tool calls fire in sequence:
Schema discovery: "What tables and columns are in the health database?"
Analysis: "What's the correlation between my step count and sleep quality over the last 30 days?"
Should trigger:
get_insights→get_data_dictionary→run_analysis→save_insight
Chart: "Show me my resting heart rate trend as a chart."
Should trigger:
run_analysis→generate_chart→ returns a file path
Memory: "What do you already know about my health patterns?"
Should trigger:
get_insightsand return stored findings without re-running anything
3. Standalone agent CLI
uv run python mcp_server/agent.py 2026-02-18Tests the non-MCP path (summarizer + readiness + scheduling) and confirms nothing broke during the Phase 1–4 additions.
Available Tools
5 toolscalculate_readiness_scoreA
Calculate a 1-10 readiness score based on sleep quality, resting heart rate, and prior-day exertion. Use this to decide when to schedule demanding tasks.
Args: target_date: ISO date string (YYYY-MM-DD). Defaults to today.
Inputs: target_date.
get_health_summaryB
Get an aggregated health summary (sleep, activity, heart rate) for a date.
Args: target_date: ISO date string (YYYY-MM-DD). Defaults to today.
Inputs: target_date.
get_tasksB
Return the current task list from todo.json. Each task has an energy_required level (high/medium/low) and preferred_time slot.
Inputs: no named parameters. Returns: result
propose_scheduleB
Propose an energy-aware daily schedule based on today's readiness score and the task list. High-energy tasks are placed when readiness supports them.
Args: target_date: ISO date string (YYYY-MM-DD). Defaults to today.
Inputs: target_date.
query_raw_logsA
Run a read-only SQL query against the health database.
Available tables:
sleep_logs (date, bedtime, wake_time, total_hours, deep_sleep_hours, rem_sleep_hours, awakenings)
activity_logs (date, steps, active_minutes, calories_burned, workouts)
heart_rate_logs (date, timestamp, bpm)
Args: query: A SELECT SQL query. Only read operations are allowed.
Inputs: query (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose with no overlap: calculate_readiness_score computes a score, get_health_summary aggregates data, get_tasks retrieves tasks, propose_schedule creates a schedule, and query_raw_logs runs SQL queries. The descriptions make it easy to differentiate them, preventing misselection.
The naming is mostly consistent with a verb_noun pattern (e.g., calculate_readiness_score, get_health_summary, get_tasks, propose_schedule), but query_raw_logs deviates slightly by using 'query' as a verb instead of a more standard action like 'get' or 'fetch'. However, the pattern is still readable and coherent overall.
With 5 tools, the server is well-scoped for a wellness planner domain. Each tool serves a specific function in the workflow—from data retrieval and calculation to scheduling and querying—without being too sparse or bloated, making it efficient for agents to use.
The tool set covers core wellness planning operations: calculating readiness, summarizing health data, managing tasks, proposing schedules, and querying raw logs. A minor gap is the lack of tools for updating or modifying tasks or health data (e.g., add_task, update_health_log), but agents can work around this using the existing tools for read and propose operations.
Maintenance
Related MCP Connectors
N-of-1 health experiments in your AI assistant: Oura/RescueTime data, protocols, workouts.
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
Ask Claude, ChatGPT or Cursor about your Apple Health data: workouts, sleep, food. Read-only.
Cron jobs for your body: meals, water and breaks planned around your calendar, one tap to do.
Related MCP Servers
- FlicenseBqualityDmaintenanceA personal fitness tracking server that enables logging and querying workouts, nutrition, and body metrics through a local SQLite database. Integrates with OpenNutrition MCP for food logging and supports exercise history tracking for workout progression.17-
- FlicenseNot gradedqualityDmaintenanceEnables natural language task management including logging, updating, and summarizing productivity activities across multiple categories using a local SQLite database. It allows users to manage workflows and generate time-based summaries through standardized Model Context Protocol tools.1-
- AlicenseAqualityFmaintenanceAggregates and analyzes fitness data from multiple sources like Whoop and Strava through a modular adapter architecture. It enables users to monitor health metrics, track activities, and gain insights into sleep, recovery, and training performance.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables users to track daily calorie consumption by logging meals through natural language and searching a comprehensive food database. It provides daily summaries, weekly reports, and persistent SQLite storage to monitor dietary trends and goals.7 npmMIT