CLI & MCP Server

@supstack/cli ist ein quelloffener Kommandozeilen-Client und MCP-Server über der öffentlichen SupStack-API. Nur-lesend, kein Konto nötig. Open source (MIT). Thin client over the public SupStack API.

Quellcode auf GitHub ansehen →@supstack/cli auf npm →

Installation

brew install drbaher/supstack/supstack

…oder über npm:

npm install -g @supstack/cli

…oder ohne Installation ausführen:

npx -y @supstack/cli research magnesium

Aktiviere danach die Tab-Vervollständigung: supstack completion install

Befehle

Häng --json an jeden Befehl für maschinenlesbare Ausgabe an. Jeder Befehl entspricht einem MCP-Tool mit derselben Fähigkeit.

supstack research <slug>supstack_research

Full evidence summary for one supplement — description, evidence score, dosage, and safety profile (warnings + drug interactions).

--protocol: Include the dosing protocol
--synergies: Include supplement synergies

supstack research magnesium --protocol

supstack research ashwagandha --json

supstack search [query]supstack_search

Search supplements by name (fuzzy), or filter the library by goal, category, type, minimum evidence, or safety rating.

-g, --goal <goal>: Filter by goal id (e.g. deep-sleep)
-c, --category <category>: Filter by category
-t, --type <type>: Filter by supplement type
-e, --evidence <level>: Minimum evidence: emerging | moderate | strong | very-strong
-s, --safety <rating>: Filter by safety: high | moderate | caution
-n, --limit <n>: Max results (default 10)

supstack search magnesium

supstack search --goal deep-sleep --evidence strong -n 5

supstack compare <a> <b> [c]supstack_compare

Compare 2–3 supplements head-to-head by evidence score, safety rating, and total studies, with per-category winners.

supstack compare magnesium glycine

supstack compare creatine beta-alanine citrulline

supstack studies [query]supstack_studies

Search the peer-reviewed research library by free-text query, study type, and supplement.

-t, --type <type>: Study type (e.g. rct, meta-analysis, systematic-review)
-s, --supplement <slug>: Filter by supplement slug
--sort <field>: Sort: newest | relevance | year (default newest)
-n, --limit <n>: Max results (default 10)

supstack studies sleep --type rct

supstack studies --supplement creatine --sort year

supstack interactions <supplements...>supstack_interactions

Check interactions across supplements. With --medication, checks each supplement against a drug (clinical severity). With --pathway on a pair, runs the biochemical engine (shared enzyme/receptor targets, mechanisms, synergy/conflict score).

--pathway: Deep biochemical pathway analysis (exactly 2 supplements)
-m, --medication <drug>: Check each supplement against a medication (e.g. lisinopril)

supstack interactions magnesium ashwagandha

supstack interactions caffeine l-theanine --pathway

supstack interactions magnesium potassium --medication lisinopril

supstack stack <add|remove|list> [slug]supstack_stack

Manage a local supplement stack stored in ~/.supstack/ (with optional per-supplement dose/timing/brand). Logged-in users can also sync it with their account (stack pull | push | sync — see Account commands).

--dose <dose>: Dosage for `add` (e.g. 400mg)
--timing <timing>: Timing for `add` (e.g. bedtime)
--brand <brand>: Brand for `add`

supstack stack add magnesium --dose 400mg --timing bedtime

supstack stack list

supstack rate [supplements...]supstack_rate_stack

Grade a stack A–F (and 0–100) by how well it covers your goals, with a per-goal coverage breakdown and the gaps. Supplements default to your local stack; goals come from --goals, else your account goals when signed in, else they are inferred from the stack.

-g, --goals <list>: Comma-separated goal ids (else account goals, else inferred)
--cloud: Rate your synced cloud stack instead of the local one (requires login)

supstack rate --goals deep-sleep,sharpen-focus

supstack rate magnesium l-theanine

supstack exportsupstack_export

Export your local stack as a Markdown or JSON document, with each supplement’s details fetched from the API.

-f, --format <format>: Output format: md | json (default md)

supstack export --format md

supstack export --format json

supstack goals [query]supstack_goals

List health goal ids (names, grouped by category) — the ids that `rate` and `recommend` expect. Filter by a free-text query or --category.

-c, --category <id>: Filter by category id (e.g. sleep, mental)

supstack goals --category sleep

supstack goals strength

supstack define <term>supstack_define

Look up a scientific or supplement glossary term and its aliases.

supstack define bioavailability

supstack define adaptogen

Konto-Befehle

Erfordern supstack login — sie wirken auf dein angemeldetes Konto. Lesezugriffe bleiben vollständig anonym; ein Konto schaltet Personalisierung frei.

supstack login

supstack logout

Sign out and revoke this device's token.

supstack whoami

Show the signed-in account.

supstack stack pull | push | sync

Sync your local stack with your account: pull (cloud→local), push (local→cloud), sync (additive merge, preserves dosage/timing/brand).

supstack profile [set | clear]

View or update your health profile (age, sex, weight, conditions, medications, goals, lifestyle).

supstack recommend

Personalized supplement recommendations from your saved goals + cloud stack.

supstack experiments list | show <id>

View your N-of-1 experiments and their verdicts and check-ins.

supstack experiments protocol | start | check-in | abandon

Run the N-of-1 loop: preview a protocol, start an experiment (baseline answers via --answer id=value), submit check-ins and get the verdict, or abandon an in-progress one.

supstack track log [supplement] | adherence

Log doses (whole stack if omitted) and view your adherence rate, streak, and per-supplement breakdown.

MCP-Server

supstack mcp startet einen Model-Context-Protocol-Server über stdio und stellt jede oben genannte Fähigkeit als Tool bereit. Das CLI und die MCP-Tools werden aus einer Registry generiert, sie driften also nie auseinander.

Claude Code

claude mcp add supstack -- npx -y @supstack/cli mcp

Claude Desktop — `claude_desktop_config.json`

{
  "mcpServers": {
    "supstack": {
      "command": "npx",
      "args": ["-y", "@supstack/cli", "mcp"]
    }
  }
}

Tools (21)

supstack_research	Full evidence summary for one supplement — description, evidence score, dosage, and safety profile (warnings + drug interactions).
supstack_search	Search supplements by name (fuzzy), or filter the library by goal, category, type, minimum evidence, or safety rating.
supstack_compare	Compare 2–3 supplements head-to-head by evidence score, safety rating, and total studies, with per-category winners.
supstack_studies	Search the peer-reviewed research library by free-text query, study type, and supplement.
supstack_interactions	Check interactions across supplements. With --medication, checks each supplement against a drug (clinical severity). With --pathway on a pair, runs the biochemical engine (shared enzyme/receptor targets, mechanisms, synergy/conflict score).
supstack_stack	Manage a local supplement stack stored in ~/.supstack/ (with optional per-supplement dose/timing/brand). Logged-in users can also sync it with their account (stack pull \| push \| sync — see Account commands).
supstack_rate_stack	Grade a stack A–F (and 0–100) by how well it covers your goals, with a per-goal coverage breakdown and the gaps. Supplements default to your local stack; goals come from --goals, else your account goals when signed in, else they are inferred from the stack.
supstack_export	Export your local stack as a Markdown or JSON document, with each supplement’s details fetched from the API.
supstack_goals	List health goal ids (names, grouped by category) — the ids that `rate` and `recommend` expect. Filter by a free-text query or --category.
supstack_define	Look up a scientific or supplement glossary term and its aliases.
supstack_recommend	Personalized recommendations from the user’s saved goals + cloud stack. Requires login.
supstack_profile_get	Read the user’s health profile. Requires login.
supstack_profile_set	Update the user’s health profile (mutating). Requires login.
supstack_experiments_list	List the user’s N-of-1 experiments. Requires login.
supstack_experiments_get	Get one experiment in full (protocol, verdict, check-ins). Requires login.
supstack_experiment_protocol	Preview an N-of-1 protocol’s baseline + check-in questions. Requires login.
supstack_experiment_start	Start an N-of-1 experiment with baseline answers (mutating). Requires login.
supstack_experiment_check_in	Submit an experiment check-in; computes the verdict on the final one (mutating). Requires login.
supstack_experiment_abandon	Stop an in-progress experiment — sets it to abandoned (mutating). Requires login.
supstack_track_log	Log a supplement dose (mutating). Requires login.
supstack_track_adherence	Adherence rate, streak, and per-supplement breakdown. Requires login.

Konfiguration

Umgebungsvariable	Standard	Zweck
SUPSTACK_API_URL	https://supstack.me/api/v1	API base URL (override for local dev)
SUPSTACK_API_KEY	—	Optional API key (anonymous works at 60/min/IP)
SUPSTACK_CACHE_TTL	3600	Response cache TTL in seconds
SUPSTACK_NO_CACHE	—	Set to disable the local response cache
SUPSTACK_TIMEOUT	20	Per-request timeout in seconds (or use --timeout)
SUPSTACK_HOME	~/.supstack	Directory for config, stack, and cache
SUPSTACK_TOKEN	—	Override the stored account token (from supstack login)
SUPSTACK_NO_ANON_TOKEN	—	Disable auto-minting of the anonymous instant-token
SUPSTACK_NO_UPDATE_CHECK	—	Disable the "update available" notice (also honours NO_UPDATE_NOTIFIER)
SUPSTACK_COMPLETE_TIMEOUT	2500	Per-request budget (ms) for a TAB-time completion fetch
NO_COLOR	—	Disable ANSI colour

Shell-Vervollständigung

Dynamische Vervollständigung für bash, zsh und fish — vervollständigt Befehle, Unteraktionen, Supplement-Slugs und Ziel-IDs. Generiere das Skript für deine Shell und wärm danach den Wert-Cache einmal auf.

supstack completion bash >> ~/.bashrc

supstack completion refresh

Exit-Codes

Befehle beenden sich mit einem semantischen Code, damit Skripte und MCP-Wrapper nach der Art des Fehlers verzweigen können.

Code	Bedeutung
0	Success
1	Generic error (including 5xx)
2	Auth required or rejected (not logged in, 401, 403)
3	Not found (404)
4	Rate limited (429)
5	Network failure / timeout
6	Invalid input (bad/missing args or flags, unknown command, 400/422)

SupStack liefert evidenzbasierte Informationen für allgemeines Wohlbefinden und Bildung. Das ist keine medizinische Beratung und nicht dazu gedacht, Krankheiten zu diagnostizieren, zu behandeln, zu heilen oder ihnen vorzubeugen. Sprich mit einer qualifizierten medizinischen Fachperson, bevor du deine Supplement-Routine änderst.