MCP 服务器

Wellness Nourish

A local-first nutrition MCP server for food search, barcode lookup, meal estimation, intake logging, hydration, and nutrition coaching workflows.

README

<h1 align="center">Wellness Nourish</h1>

<h3 align="center"> Local-first nutrition MCP — food search, barcode lookup, intake logging, hydration. Works without OAuth.<br> Local-first MCP server — <strong>tokens never leave your machine</strong>. </h3>

<p align="center"> <strong>📈 Published on npm and used by AI agents and MCP clients</strong> — see the live <a href="https://www.npmjs.com/package/wellness-nourish">download badge</a> above for current numbers.<br> <sub>If Nourish helps your agent, a ⭐ on this repo makes it easier for other AI builders to find.</sub> </p>

⚡ One-command install — pick your runtime:

Delx Wellness for Hermes: npx -y delx-wellness-hermes setup

Delx Wellness for OpenClaw: npx -y delx-wellness-openclaw setup

Both preconfigure this connector and the full Delx Wellness stack into a dedicated profile. Or wire it standalone into Claude Desktop / Cursor / ChatGPT Desktop — see the install section below.

Want runnable agent examples? Use the Delx Agent Workbench for prompt packs, MCP client configs and local-first workflow templates.

Overview

Wellness Nourish is a local MCP server for nutrition search, barcode lookup, barcode photo lookup, photo-assisted meal estimation, intake logging, hydration, goals, exports, daily or weekly summaries, personal meal memory, and coach-style nutrition workflows. It runs over stdio by default for MCP clients and can also run a Streamable HTTP endpoint at POST /mcp.

If this nutrition layer helps your agent workflow, please star the repo. Stars make the project easier for other AI builders to discover and help Delx keep shipping local-first wellness infrastructure.

Field guide: Why local-first wellness agents need MCP.

Try It In 60 Seconds

npx -y wellness-nourish doctor
npx -y wellness-nourish search banana
npx -y wellness-nourish barcode 0000000000000
npx -y wellness-nourish log --preview "2 ovos, banana e café preto"

Demo (offline, no API key)

NOURISH_FIXTURE_MODE=1 serves the bundled fixtures/ instead of calling USDA or Open Food Facts, so you can see the exact shape of every response with zero network access or keys. The outputs below are captured verbatim from this mode:

$ NOURISH_FIXTURE_MODE=1 wellness-nourish search banana
Bananas, raw	usda	89 kcal/100g
BANANA	usda	312 kcal/100g

$ NOURISH_FIXTURE_MODE=1 NOURISH_OFF_ENABLED=1 wellness-nourish barcode 737628064502

{
  "name": "Peanut Butter",
  "barcode": "737628064502",
  "brand": "Fixture Foods",
  "serving": { "quantity": 1, "unit": "serving", "grams": 32 },
  "nutrients_per_serving": {
    "calories_kcal": 188.16,
    "protein_g": 8,
    "carbohydrates_g": 6.4,
    "fat_g": 16,
    "fiber_g": 1.92,
    "sugar_g": 2.88,
    "saturated_fat_g": 3.2,
    "sodium_mg": 128
  },
  "license": { "name": "Open Food Facts ODbL" },
  "data_quality": { "completeness": "high", "confidence": 0.75, "warnings": [] }
  // ...full record also includes nutrients_per_100g, available_portions, carbon
}

log --preview estimates a meal locally without writing anything:

$ wellness-nourish log --preview "2 eggs and a banana"

{
  "would_write": false,
  "total_nutrients": {
    "calories_kcal": 248.02,
    "protein_g": 13.89,
    "carbohydrates_g": 27.65,
    "fat_g": 9.89,
    "fiber_g": 3.07,
    "sugar_g": 14.43
  },
  "confidence": 0.7,
  "warnings": ["Nutrition values are estimates from simple food defaults."]
  // ...full record also includes per-item breakdown and entry_preview
}

For the full Telegram/Hermes flow:

npx -y delx-wellness-hermes setup
hermes -p delx-wellness

The connector uses USDA FoodData Central as the primary food search provider. Open Food Facts is used for packaged-food barcode lookup and product-name search when enabled. Local barcode image decoding is supported with ZXing. Meal photos are estimated only from an agent-provided visual observation and always require confirmation before logging. The local estimator includes a pt-BR/Brazilian-food catalog for common meals, kitchen units, and shortcuts such as arroz, feijão, frango, ovos, banana, tapioca, picanha, feijoada and salada. It does not provide hosted sync, autonomous photo upload, recipe generation, or medical advice.

Install

npm install
npm run build

Run the MCP server over stdio:

npm start

Run Streamable HTTP locally:

node dist/index.js --http

ChatGPT App / MCP Apps UI

Nourish also exposes a compact MCP Apps-compatible dashboard for ChatGPT and other compatible hosts:

Tool: nourish_chatgpt_dashboard
UI resource: ui://widget/nourish-dashboard-v1.html
MIME type: text/html;profile=mcp-app

The dashboard shows the daily nutrition summary, hydration progress, profile gaps and next-meal coaching, and it can call nourish_estimate_meal from the embedded UI for preview-only estimates. It does not write intake, water or goals; mutating tools still require explicit user confirmation through the normal MCP tools.

Optional environment:

FDC_API_KEY=your_usda_key
NOURISH_OFF_ENABLED=1
NOURISH_LOCAL_DIR=~/.wellness-nourish
NOURISH_MCP_PORT=3000

Agents should never ask users to paste API keys, tokens, raw health exports, or private food logs into chat. Configure secrets through environment variables or local files.

CLI Commands

wellness-nourish status
wellness-nourish doctor
wellness-nourish setup --client claude
wellness-nourish search banana
wellness-nourish barcode 0000000000000
wellness-nourish log --preview --meal breakfast "2 eggs and banana"
wellness-nourish log "2 eggs and banana"
wellness-nourish list 2026-05-05
wellness-nourish edit --entry intake_id --meal snack --notes "corrected"
wellness-nourish today --format markdown
wellness-nourish weekly --format markdown
wellness-nourish goals --set-calories 2200 --set-protein 120 --set-water 2500
wellness-nourish water 500 --date 2026-05-05
wellness-nourish water today --date 2026-05-05
wellness-nourish export --format csv
wellness-nourish clear-day 2026-05-05 --yes
wellness-nourish delete --entry intake_id

No arguments start the stdio MCP server. --http starts HTTP transport, --version prints the package version, and --help prints usage.

log --preview estimates without writing. Mutating MCP tools require explicit user intent; CLI commands are treated as explicit user actions, while destructive clear-day requires --yes.

The local estimator understands common lightweight portions such as g, oz, cup, tbsp, tsp, slice, piece, and serving. It still reports confidence and warnings because these are conservative tracking estimates, not lab-grade nutrition facts.

MCP Client Config Examples

Ready-to-use examples live in examples/:

examples/claude-desktop.json
examples/codex.json
examples/cursor.json
examples/windsurf.json
examples/hermes.md
examples/hermes-skill.md
examples/openclaw.md

Claude Desktop style:

{
  "mcpServers": {
    "nourish": {
      "command": "npx",
      "args": ["-y", "wellness-nourish"],
      "env": {
        "FDC_API_KEY": "${FDC_API_KEY}",
        "NOURISH_OFF_ENABLED": "1"
      }
    }
  }
}

Hermes / Telegram Personal Setup

For a personal Hermes server connected to your Telegram bot, let the package write the Hermes config and skill:

npx -y wellness-nourish setup --client hermes --profile david --local-dir /root/.hermes/nourish/david
npx -y wellness-nourish doctor --client hermes --json
hermes mcp test nourish

This adds a nourish MCP server block to ~/.hermes/config.yaml, installs ~/.hermes/skills/nourish-mcp/SKILL.md, and pins the npm package version. After config changes, use /reload-mcp or hermes mcp test nourish.

Hermes setup also writes ~/.hermes/scripts/nourish-mcp-wrapper.sh. The wrapper sources ~/.hermes/secrets/nourish.env when present, so FDC_API_KEY can be managed as a server-side secret without pasting it into chat or relying on a stale shell session.

Recommended Telegram flow:

User says what they ate.
Hermes calls nourish_estimate_meal and replies with calories, protein, confidence and warnings.
For barcode photos, Hermes calls nourish_lookup_barcode_image when it has an image path, base64 image, or data URI.
For mixed food photos, Hermes calls nourish_analyze_food_image with barcode observations, label OCR, detected items, or image description.
For meal photos, Hermes describes visible food and portions, calls nourish_estimate_meal_photo, and asks for portion confirmation.
For "what should I eat now?" questions, Hermes calls nourish_daily_coach or nourish_suggest_next_meal, optionally passing wearable context from WHOOP/Garmin/Oura.
For repeated meals, Hermes can call nourish_remember_meal after explicit user intent so future phrases like "meu café normal" expand locally.
User confirms saving.
Hermes calls nourish_log_intake with explicit_user_intent: true.
User can ask for today, weekly summaries, goals, hydration, edits, deletes or exports.

Local build:

{
  "mcpServers": {
    "nourish": {
      "command": "node",
      "args": ["/absolute/path/to/wellness-nourish/dist/index.js"],
      "env": {
        "NOURISH_LOCAL_DIR": "/absolute/path/to/.wellness-nourish"
      }
    }
  }
}

Provider Attribution

USDA FoodData Central is the primary provider for generic food search and nutrient data. USDA data is public domain or otherwise provided by USDA FoodData Central terms; keep provider attribution with derived results.

Open Food Facts barcode data is licensed under the Open Database License (ODbL). Open Food Facts metadata has share-alike obligations, so agents and downstream tools should preserve attribution and license metadata when exporting or reusing packaged-food records.

Privacy

Intake data is stored locally under ~/.wellness-nourish/intake.jsonl unless NOURISH_LOCAL_DIR is set. Hydration is stored in hydration.jsonl, and goals are stored in goals.json in the same local directory. The connector does not require hosted accounts and does not send local intake logs to Delx Wellness. Provider lookups may contact USDA FoodData Central or Open Food Facts unless fixture mode is enabled.

Use nourish-mcp export to print the local JSONL export, nourish-mcp export --format csv for CSV, nourish-mcp delete --entry <id> to delete a specific intake entry, or nourish-mcp clear-day <date> --yes to delete all intake entries for a day.

Not Medical Advice

Nutrition estimates are approximate and intended for personal tracking and agent workflow context. They are not diagnosis, treatment, or medical advice. Confirm important nutrition decisions with a qualified professional.

Development And Tests

npm run typecheck
npm run build
npm run smoke:http
npm run test:cli-ux
npm run test:agent-readiness
npm test

Fixture mode:

NOURISH_FIXTURE_MODE=1 NOURISH_FIXTURE_DIR=fixtures npm run test:cli-ux

Delx Wellness

Project page: https://wellness.delx.ai/nutrition

Provider	Package	Repo
WHOOP	`whoop-mcp-unofficial`	whoop-mcp
Oura	`oura-mcp-unofficial`	ouramcp
Garmin	`garmin-mcp-unofficial`	garminmcp
Strava	`strava-mcp-unofficial`	strava-mcp
Fitbit	`fitbit-mcp-unofficial`	fitbitmcp
Google Health	`google-health-mcp-unofficial`	google-health-mcp
Withings	`withings-mcp-unofficial`	withingsmcp
Apple Health	`apple-health-mcp-unofficial`	apple-health-mcp
Samsung Health	`samsung-health-mcp-unofficial`	samsung-health-mcp
Polar	`polar-mcp-unofficial`	polarmcp
Nourish (nutrition)	`wellness-nourish`	wellness-nourish

📧 Contact & Support

📨 support@delx.ai — general questions, integration help, partnerships
🐛 Bug reports / feature requests — GitHub Issues
🐦 Updates — @delx369 on X
🌐 Site — wellness.delx.ai