Wellness Cycle Coach

io.github.davidmosiahPublished by GitHub account davidmosiahv0.3.5Updated Oct 25, 2026

Local-first cycle coach MCP for phase-aware nutrition and training context.

VerifiedSTDIODesktop onlyLocation & LifestyleAI & ML

Overview

AI-generated overview

Local, stateless MCP server that turns period start dates into menstrual-cycle phase estimates and phase-aware nutrition, training and hydration guidance.

What you can do
  • Estimate the current cycle phase, cycle day and confidence from supplied period start dates, and predict the next period from average cycle length.
  • Get phase-aware nutrition, training and hydration recommendations, or a single combined full report for the current phase.
  • Screen for irregular or PCOS-like cycles from history and request guidance for any specific phase.
  • Inspect the server itself: runtime contract, capabilities, connection status, privacy audit, data inventory, quickstart and demo responses.
  • Read, onboard and update an opt-in local wellness profile of non-secret preferences.
When to use it
Useful when an assistant should adapt fitness, nutrition or recovery advice to where someone is in their menstrual cycle, including irregular or PCOS-aware cases, and when cycle data should stay on the local machine rather than be stored by a service.
Requirements
Runs as a local process via npx (Node.js) over stdio by default; an optional Streamable HTTP mode binds to loopback only and is configured with WELLNESS_CYCLE_COACH_HOST, WELLNESS_CYCLE_COACH_PORT and WELLNESS_CYCLE_COACH_TRANSPORT. No account, API key or network access is needed; period dates are passed in as tool arguments.
Before you install
Cycle data is health-sensitive: the server states it is stateless and makes no outbound calls, but the dates still pass through the assistant and its model provider. The profile tools write non-secret preferences to a local file under the user's home directory and require explicit user intent. Output is not medical advice, diagnosis, fertility tracking or contraception guidance. The README describes version 0.5.0 as a release candidate, not evidence of publication.

Installation

In SourceWeft

  1. Open Wellness Cycle Coach in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Wellness Cycle Coach

Menstrual cycle coach MCP for AI agents — now with PCOS-aware mode.
Built so AI finally serves the 50% of users agents have ignored — without ever storing cycle data.

[npm version] [npm downloads] [License MIT] [Site]

[GitHub stars] [Built for MCP] [Hermes] [OpenClaw]

🌙 Why this exists: Most AI agents treat the body as a single context-free unit. But energy, recovery, training tolerance, nutrient needs and even cognitive bandwidth shift across the menstrual cycle. wellness-cycle-coach gives any agent phase-aware guidance — and never stores cycle data to do it.

⚡ One-command install — pick your runtime:

HTTP (v2 stateless)

Default is stdio. Optional Streamable HTTP — no session id, JSON responses, loopback only:

bash
npx -y [email protected] --http# GET  http://127.0.0.1:3000/health# POST http://127.0.0.1:3000/mcp   (sessionless)

Env: WELLNESS_CYCLE_COACH_HOST, WELLNESS_CYCLE_COACH_PORT, WELLNESS_CYCLE_COACH_TRANSPORT=http.

Overview

Pass in period start dates (from any source — Apple Health Cycle, Garmin women's health, Fitbit female health, or direct user input) and get back the user's current phase plus phase-aware recommendations for nutrition, training, and hydration. Stateless — the MCP itself never persists cycle data. Supports PCOS-aware mode via the cycle_irregular flag (v0.3.3) — accepts cycles 21-90 days, caps confidence at 'low', and returns a luteal_extended placeholder when standard 14-day-luteal math no longer applies.

Try It In 60 Seconds

bash
npx -y [email protected] doctor
# Or use the MCP directly via your client:# {#   "mcpServers": {#     "wellness-cycle-coach": {#       "command": "npx",#       "args": ["-y", "[email protected]"]#     }#   }# }

Then in your agent:

json
{  "name": "cycle_full_report",  "arguments": {    "history": [      { "start_date": "2026-04-01" },      { "start_date": "2026-04-29" }    ]  }}

Returns current phase + nutrition emphasize/moderate/avoid + training style/intensity + hydration target + next-period estimate.

Tools (17)

ToolPurpose
cycle_agent_manifestRuntime contract
cycle_capabilitiesPhases, upstream connectors, metrics
cycle_connection_statusHealth + stateless reminder
cycle_privacy_auditWhat's logged (nothing) vs sent out (nothing)
cycle_data_inventoryPhase taxonomy + metric catalog
cycle_estimate_phaseCurrent phase + cycle day + confidence
cycle_predict_next_periodAverage cycle length + next-period date
cycle_phase_guidanceRecommendations for any specific phase
cycle_recommend_nutritionPhase-aware nutrition for current phase
cycle_recommend_trainingPhase-aware training for current phase
cycle_full_reportSingle-call combined report
cycle_irregular_checkPCOS / irregular-cycle screening from history
cycle_quickstartMinimal getting-started walkthrough
cycle_profile_getRead the shared Delx Wellness profile (read-only)
cycle_profile_updatePersist opt-in profile prefs (requires explicit user intent)
cycle_onboarding11-question onboarding flow for the shared profile
cycle_demoSample request/response for quick exploration

The 4-phase model

PhaseWhenEnergyNutrition emphasisTraining
menstrualdays 1 → period end (~5)LowerIron + magnesium + omega-3Restorative (yoga, walking, mobility)
follicularpost-period → ovulation - 2Rising / peakComplex carbs + lean protein + fermented foodsBuild (strength, sprints, new skills)
ovulatoryovulation ± 1 dayPeakAntioxidants + zincPeak (PRs, plyometrics)
lutealovulation + 2 → next periodFallingB vitamins + magnesium + complex carbsEndurance + technique

Why stateless?

Menstrual cycle data is medical-record sensitive. The strongest privacy guarantee is to never store it. Other apps (Flo, Clue) live by hoarding cycle data on their servers; this MCP refuses to participate. The agent passes data in, the coach returns guidance, the data evaporates.

Cross-connector wedge

Apple Health Cycle → period dates       ┐Garmin women's health → cycle context   ├─→ wellness-cycle-coach → phase + guidanceFitbit female health → period dates     ┘                                  │                                                                            │                                                                            ↓                                                            wellness-nourish coach                                                            (phase-aware meal planning)                                                                            │                                                            whoop-mcp / garminmcp / ouramcp                                                            (recovery-aware late-luteal load adjustments)

Privacy

  • ✅ Stateless for cycle data — period dates are never persisted; they stay in process memory for the duration of the call and evaporate.
  • ✅ Opt-in local preferences — the cycle_profile_* tools can persist non-secret wellness preferences (name, goals, devices, training/nutrition context) to ~/.delx-wellness/profile.json, but only when the user explicitly asks (cycle_profile_update requires explicit_user_intent: true). Secrets (tokens, API keys, biomarkers) are rejected at write time.
  • ✅ Offline-capable — pure-function computation. No outbound calls.
  • ✅ Tool-arg-only cycle data — the agent passes period history in via the MCP request and it stays in process memory.

Run wellness-cycle-coach doctor to inspect.

What this is NOT

  • Not medical advice or diagnosis.
  • Not a fertility tracker or contraception aid (consult a clinician).
  • Not a replacement for talking to a healthcare provider about painful, abnormal, or absent periods.
  • PCOS / irregular cycles supported via cycle_irregular: true (v0.3.3), but this is NOT a substitute for clinical care — see clinician for fertility, contraception, or symptom-management decisions.
  • Not specialized for perimenopause or post-pill (yet — see CONTRIBUTING.md).

Roadmap

  • v0.2 — adapters for apple-health-mcp / garminmcp / fitbitmcp so agents can pull period history with one MCP call.
  • v0.3 — symptom logging surface + symptom-aware guidance adjustments (cramps → magnesium emphasis, mood drop → B-vitamin emphasis).
  • v0.4 — non-English locale support starting with pt-BR.

📧 Contact & Support

License

MIT — see LICENSE.

wellness-cycle-coach is independent research-software. Not affiliated with Clue, Flo, Stardust, or any other cycle-tracking app. Not medical advice.

Skill or MCP

Same package, two doors. MCP registers tools on stdio/HTTP. The skill can drive the same tools through the CLI when the client has no MCP:

bash
npx -y [email protected] call cycle_connection_status --json '{}'

Copy skill/SKILL.md into your agent skills dir.

0.5.0 — candidate (2026-11-02)

This is a release candidate, not evidence of an npm publication. Existing installations are not updated automatically.

Migration and security boundaries

  • HTTP transport accepts loopback only. LAN addresses and wildcard binds are rejected; use stdio or a local loopback client instead.
  • Wellness profiles are validated, limited to 256 KiB, and protected with a cooperative lock. Oversized or invalid existing profiles must be corrected before use. Symbolic links, including dangling links and legacy profile paths, are rejected. These checks do not guarantee safety against a hostile local filesystem or non-cooperating processes.
  • MCP inputs have a 10,000-element budget and HTTP bodies are limited to 1 MiB; compressed request bodies are rejected. Previously accepted oversized requests may now fail; reduce request sizes rather than disabling validation.
  • Dependency fixes are included. Upgrade explicitly after publication and restart the connector; old installations retain their previous behavior.

Source: README.md at commit a93629e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.5LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts