Supstack MCP server

@supstack/cli

Evidence-based supplement intelligence in your terminal — and an MCP server for AI agents.

A thin client over the public SupStack API. Read-only, no account required. One capability registry powers both the CLI and the MCP server.

Status: Phase 2 (accounts) in progress. All read commands below work, plus

an MCP server and login/whoami. Install with npm install -g @supstack/cli.

Install

# Homebrew (macOS / Linux)
brew install drbaher/supstack/supstack

# or npm
npm install -g @supstack/cli

# or run without installing
npx -y @supstack/cli define adaptogen

Then enable shell completion: supstack completion install.

From source (in this directory): npm install && npm run build && node dist/index.js define adaptogen.

Usage

supstack research magnesium --protocol       # full evidence summary for one supplement
supstack search --goal deep-sleep -n 5       # search by name or filter
supstack compare magnesium glycine           # 2–3 head-to-head
supstack studies "sleep" --type rct          # research library
supstack interactions caffeine l-theanine --pathway   # interaction check (deep pair analysis)
supstack interactions magnesium potassium --medication lisinopril   # supplement × drug check
supstack stack add magnesium --dose 400mg --timing bedtime   # local stack (+ dose/timing/brand)
supstack stack sync                          # sync local ⇄ your account (login required)
supstack goals --category sleep              # list goal ids (for rate/recommend)
supstack rate --goals deep-sleep,sharpen-focus   # grade your stack A–F by goal coverage
supstack experiments start magnesium deep-sleep  # run an N-of-1 experiment (requires login)
supstack export --format md                  # export your stack
supstack define bioavailability              # glossary lookup
supstack <command> --json                    # machine-readable output on any command
supstack --help

Account (Phase 2)

supstack login          # sign in via device-code flow (opens the browser to confirm)
supstack whoami         # show the signed-in account
supstack logout         # sign out and revoke this device's token

login shows a one-time code, opens https://supstack.me/activate, and finishes once you approve in the browser. The token lives in ~/.supstack/config.json (0600). Reads work fully anonymously — an account unlocks personalized features.

Once logged in, sync your stack with your account:

supstack stack pull     # local ← your account
supstack stack push     # local → your account (keeps dosage/timing/brand for kept items)
supstack stack sync     # additive merge of both; preserves existing cloud metadata

supstack profile                              # view your health profile
supstack profile set --age 35 --sex male --weight 80 --weight-unit kg
supstack recommend                            # personalized picks from your goals + stack
supstack experiments list                     # your N-of-1 experiments + verdicts
supstack track log                            # log today's stack as taken
supstack track adherence                      # your adherence rate, streak, per-supplement

As an MCP server

supstack mcp   # stdio MCP server exposing all capabilities as tools

This gives an agent the full SupStack toolset. Read-only (no account needed): supstackresearch, supstacksearch, supstackcompare, supstackstudies, supstackinteractions, supstackstack, supstackratestack, supstackexport, supstackdefine.

Shortened. The full README is on GitHub.