rogertheunissenmerge oss

@sommelierx/mcp-server

Wine pairing intelligence for AI assistants. Connect Claude, Cursor, Windsurf, or any MCP-compatible client to a sommelier-grade pairing algorithm that matches wines to your ingredients, dishes, and recipes.

Quick Start

Claude Desktop

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

{
  "mcpServers": {
    "sommelierx": {
      "command": "npx",
      "args": ["@sommelierx/mcp-server"]
    }
  }
}

That is it. Ask Claude "What wine goes with grilled salmon?" and it will use SommelierX to answer.

With a Pro API key

For recipe extraction, group pairing, and score breakdowns:

{
  "mcpServers": {
    "sommelierx": {
      "command": "npx",
      "args": ["@sommelierx/mcp-server"],
      "env": {
        "SOMMELIERX_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Cursor / Windsurf / Other MCP Clients

The same configuration works. Add the command and args to your client's MCP settings.

Available Tools

Tool	What it does	Tier
pair_wine_with_ingredients	Find wines for a list of ingredients (e.g. "salmon, lemon, dill")	Free
pair_wine_with_meal	Find wines for a dish name (e.g. "risotto ai funghi")	Free
find_meals_for_wine	Find dishes that pair with a wine style (e.g. "Barolo")	Free
search_ingredients	Search the ingredient database	Free
search_meals	Search the meal database	Free
pair_wine_with_recipe_url	Extract ingredients from a recipe URL and pair wines	Pro
group_pairing	Find the best wine across multiple dishes (e.g. 3-course dinner)	Pro

Authentication

SommelierX supports two authentication methods. You can use either one -- no need to configure both.

Option 1: API Key (subscription)

Set the SOMMELIERX_API_KEY environment variable in your MCP client config. The key format is sk_live_.... You get a monthly call allowance based on your tier (Free / Pro / Enterprise).

{
  "mcpServers": {
    "sommelierx": {
      "command": "npx",
      "args": ["@sommelierx/mcp-server"],
      "env": {
        "SOMMELIERX_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Get your API key at api.sommelierx.com.

Option 2: x402 Payment (pay per call)

No API key needed. Your AI agent pays per call using USDC on the Base network via the Coinbase x402 protocol. When a request lacks an API key, the server returns a 402 Payment Required response with a payment payload. x402-compatible agents handle this automatically.

This is ideal for:

• AI agents that manage their own wallet
• Pay-as-you-go usage without a subscription
• Agent-to-agent commerce (no human in the loop)

Pricing (per call)

Tool	Price	Tier
pair_wine_with_meal	$0.01	Free
find_meals_for_wine	$0.01	Free
search_ingredients	$0.005	Free
search_meals	$0.005	Free
pair_wine_with_ingredients	$0.02	Pro
pair_wine_with_recipe_url	$0.02	Pro
group_pairing	$0.03	Pro

With an API key, calls are deducted from your tier allowance. With x402, each call is charged at the listed price.

Example Conversations

Basic pairing:

"What wine pairs well with salmon, asparagus, and hollandaise sauce?"

Reverse pairing:

"I have a bottle of Barolo. What should I cook?"

Recipe URL:

"What wine goes with this recipe? https://www.allrecipes.com/recipe/..."

Dinner party:

"I'm planning a 3-course dinner: Caesar salad, rack of lamb, and chocolate mousse. What single wine works for all courses?"

How It Works

1. You ask your AI assistant a wine question
2. The assistant calls the appropriate SommelierX tool
3. The MCP server translates your input into structured API calls
4. SommelierX's pairing algorithm (17 food DNA dimensions x 19 wine DNA dimensions) calculates matches
5. You get scored wine recommendations based on real sommelier expertise

Ingredient Resolution

When you use pair_wine_with_ingredients, the server automatically resolves natural language ingredient names to database entries. The AI assistant does not need to know database IDs -- it passes ingredient names directly.

Configuration

Environment Variable	Required	Default	Description
SOMMELIERX_API_KEY	No	--	API key for Pro/Enterprise access. Without a key, free tier (50 calls/day).
SOMMELIERX_API_URL	No	https://api.sommelierx.com	API base URL.
SOMMELIERX_LANGUAGE	No	en	Default language for results (en, nl, fr, de, es, it).

API Tiers

Tier	Daily Limit	Per-Minute Limit	Features
Free	50 calls	2/min	Basic pairing, search, ingredient/meal lookup
Pro ($49/mo)	500 calls	20/min	+ Recipe URL extraction, group pairing, score breakdowns
Enterprise	10,000 calls	100/min	+ Custom limits, SLA

Get your API key at api.sommelierx.com

API Documentation

Full API documentation is available at docs.sommelierx.com.

The OpenAPI specification is served at https://api.sommelierx.com/api/v1/openapi.json.

Development

npm install
npm run build
npm run dev       # development mode with hot reload
npm run typecheck # type checking without emit

Requirements

• Node.js >= 18.0.0

License

MIT