CLI & MCP Server

@supstack/cli is an open-source command-line client and MCP server over the public SupStack API. Read-only, no account required. Open source (MIT). Thin client over the public SupStack API.

Install

npm install -g @supstack/cli

…or run without installing:

npx -y @supstack/cli research magnesium

Commands

Add --json to any command for machine-readable output. Every command maps to an MCP tool of the same capability.

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 two or more supplements. 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)

supstack interactions magnesium ashwagandha

supstack interactions caffeine l-theanine --pathway

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

Manage a local supplement stack stored in ~/.supstack/. The only command that writes state — everything else is read-only.

supstack stack add magnesium

supstack stack list

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 define <term>supstack_define

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

supstack define bioavailability

supstack define adaptogen

MCP server

supstack mcp runs a Model Context Protocol server over stdio, exposing every capability above as a tool. The CLI and the MCP tools are generated from one registry, so they never drift.

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 (8)

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 two or more supplements. 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/. The only command that writes state — everything else is read-only.
supstack_export	Export your local stack as a Markdown or JSON document, with each supplement’s details fetched from the API.
supstack_define	Look up a scientific or supplement glossary term and its aliases.

Configuration

Env var	Default	Purpose
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_HOME	~/.supstack	Directory for config, stack, and cache
NO_COLOR	—	Disable ANSI colour

SupStack provides evidence-based information for general wellness and education. It is not medical advice and is not intended to diagnose, treat, cure, or prevent any disease. Consult a qualified healthcare provider before changing your supplement regimen.