@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

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)

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

API Tiers

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