Suppevo MCP Server

An MCP (Model Context Protocol) server that exposes the Suppevo supplement-tracking platform API as tools for AI assistants.

Features

Category	Description
Profile	Manage user profiles and preferences
Products	CRUD, bulk operations, search (admin + public)
Supplements	Track user supplement routines
Schedules	Dosing schedules with reminders
Doses	Log and query dose history
Reviews	Create, moderate, and browse reviews
Rewards	Points, badges, streaks, challenges
Brands	Brand management and discovery
Brand Owners	Brand owner portal tools
Ingredients	CRUD, search, bulk ops, intelligence
Ingredient Intelligence	Alternatives, interactions, dosing guides, effectiveness
Biomarkers	Admin and public biomarker data
Evidence Links	Scientific evidence management
Benefits	Health benefit categories
Scoring	Product and ingredient scoring
Stack Analysis	Analyze supplement stacks
Suggestions	User and admin suggestion workflows
News	Public news feed
Exports	Data export tools
Admin	User groups, brand assignments

Quick Start

Prerequisites

• Python 3.11+
• A Suppevo API token (JWT from Cognito)

Install from PyPI

pip install suppevo-mcp

Or run directly with uvx (no install needed):

uvx suppevo-mcp

Install from source

git clone https://github.com/GomezMera-IO-LLC/suppevo-data-mcp.git
cd suppevo-data-mcp
pip install -e .

Configuration

The server loads environment variables from ~/.env (your home directory). This keeps credentials out of project files and version control.

Setup your ~/.env

Create or edit ~/.env:

# Suppevo MCP Server
SUPPEVO_API_TOKEN=your-jwt-token-here
SUPPEVO_REFRESH_TOKEN=your-refresh-token-here
SUPPEVO_CLIENT_ID=your-cognito-client-id
# SUPPEVO_API_BASE_URL=https://dev.api.suppevo.com/
# SUPPEVO_COGNITO_REGION=us-east-1

Variable	Required	Default	Description
SUPPEVO_API_TOKEN	Yes	—	JWT access token for authenticated endpoints
SUPPEVO_REFRESH_TOKEN	No	—	Cognito refresh token for auto-renewal
SUPPEVO_CLIENT_ID	No	—	Cognito app client ID (needed for token refresh)
SUPPEVO_API_BASE_URL	No	https://dev.api.suppevo.com/	API base URL
SUPPEVO_COGNITO_REGION	No	us-east-1	AWS region for Cognito

Note: Environment variables passed directly (e.g. via MCP client env config) take precedence over values in ~/.env.

Getting your API token

1. Sign in to the Suppevo app
2. Retrieve your JWT token from the authenticated session (IdToken from Cognito)
3. Optionally grab the refresh token and client ID for automatic token renewal

MCP Client Setup

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "suppevo": {
      "command": "uvx",
      "args": ["suppevo-mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "suppevo": {
      "command": "uvx",
      "args": ["suppevo-mcp"]
    }
  }
}

Credentials are loaded automatically from ~/.env — no need to put tokens in MCP config files.

Running from source (development)

If you cloned the repo and want to point your MCP client at the local code:

{
  "mcpServers": {
    "suppevo": {
      "command": "python3",
      "args": ["-m", "suppevo_mcp"],
      "cwd": "/path/to/suppevo-data-mcp"
    }
  }
}

Usage

Once configured, your AI assistant will have access to all Suppevo tools. Examples:

• "Search for magnesium supplements"
• "Show my current supplement stack"
• "Log a dose of Vitamin D — 5000 IU taken this morning"
• "What are the interactions for ashwagandha?"
• "Create a new product called 'Omega-3 Fish Oil' in the heart category"
• "Show my points balance and current streak"

Public vs Authenticated Tools

• Public tools (prefixed with public_) work without authentication and are read-only
• Authenticated tools require SUPPEVO_API_TOKEN and provide full CRUD access
• Admin tools require an admin-level token for write operations on products, brands, ingredients, etc.

Token Refresh

If you provide SUPPEVO_REFRESH_TOKEN and SUPPEVO_CLIENT_ID, the server will automatically refresh expired access tokens via AWS Cognito. This prevents interruptions during long sessions.

Without a refresh token, you'll see a 401 error when the token expires and will need to update the token in your MCP config and restart.

Development

# Install in editable mode
pip install -e .

# Run the server directly
python3 -m suppevo_mcp

# Test with MCP inspector
npx @modelcontextprotocol/inspector python3 -m suppevo_mcp

Transport

The server uses stdio transport by default, which is the standard for MCP client integrations.

License

MIT