Shoppable MCP

A Model Context Protocol (MCP) server that lets Claude (and other MCP-compatible AI assistants) search products and surface trackable Where-To-Buy retailer links powered by Wayvia.

Once installed, you can ask your AI assistant things like:

"Where can I buy [product name]?" "Find retailers stocking SKU [your-sku]."

…and it will return live retailer names, prices, stock status, and trackable purchase links.

Prerequisites

1. Claude Desktop — download from https://claude.ai/download.
2. Node.js 22 or newer — download the LTS installer from https://nodejs.org/. To check what you have, open Terminal (macOS) or PowerShell (Windows) and run:

   node --version

   If it prints v22.x.x or higher, you're set.
3. Wayvia credentials — your Wayvia account manager will provide:
   • WAYVIA_CLIENT_ID
   • WAYVIA_CONFIG_ID
   • WAYVIA_TOKEN

Install

You don't need to download or build anything — Claude will fetch the shoppable-mcp package on demand via npx.

1. Open the Claude Desktop config file

macOS:

open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows (PowerShell):

notepad $env:APPDATA\Claude\claude_desktop_config.json

If the file doesn't exist yet, create it with {} as its contents.

2. Add the shoppable server

Merge the shoppable entry below into the mcpServers block, replacing the three placeholder values with the credentials your account manager sent:

{
  "mcpServers": {
    "shoppable": {
      "command": "npx",
      "args": ["-y", "shoppable-mcp@latest"],
      "env": {
        "WAYVIA_CLIENT_ID": "<your-client-id>",
        "WAYVIA_CONFIG_ID": "<your-config-id>",
        "WAYVIA_TOKEN": "<your-token>"
      }
    }
  }
}

3. Restart Claude Desktop

Fully quit Claude (⌘Q on macOS, right-click → Quit on Windows — closing the window is not enough), then reopen it.

4. Verify

In a new chat, ask Claude to look up one of your products by name or SKU. If you see retailer names, prices, and redir.wayvia.com purchase links, you are good to go.

Local development (optional)

If you've cloned this repository and want Claude to run your local build instead of the published npm package — for example to test changes before release — use a second server entry alongside shoppable.

1. Build the project

From the repo root:

npm install
npm run build

This produces dist/index.js.

2. Add a shoppable-local entry

In your claude_desktop_config.json, add a second server entry next to shoppable. Replace /absolute/path/to/shoppable-mcp with the full path to your local checkout:

{
  "mcpServers": {
    "shoppable": {
      "command": "npx",
      "args": ["-y", "shoppable-mcp@latest"],
      "env": {
        "WAYVIA_CLIENT_ID": "<your-client-id>",
        "WAYVIA_CONFIG_ID": "<your-config-id>",
        "WAYVIA_TOKEN": "<your-token>"
      }
    },
    "shoppable-local": {
      "command": "node",
      "args": ["/absolute/path/to/shoppable-mcp/dist/index.js"],
      "env": {
        "WAYVIA_CLIENT_ID": "<your-client-id>",
        "WAYVIA_CONFIG_ID": "<your-config-id>",
        "WAYVIA_TOKEN": "<your-token>"
      }
    }
  }
}

You can keep both entries active — Claude will expose tools from each under its own server name (shoppable for the published version, shoppable-local for your local build).

3. Iterate

After making code changes, rerun npm run build and fully quit + reopen Claude Desktop to pick them up.

Available tools

| Tool | What it does | |---|---| | shoppable_search | Natural-language product search. | | shoppable_retailers | Look up retailers, prices, and stock for a known SKU. |

Troubleshooting

Claude shows no shoppable tools / says the server failed to start.

• Confirm Node 22+ is installed (node --version).
• Confirm the JSON in claude_desktop_config.json is valid (no trailing commas, all braces matched). Pasting it into https://jsonlint.com is the fastest sanity check.
• Fully quit and reopen Claude — closing the window does not reload the config.

Tool calls return an authentication error.

• Re-check WAYVIA_CLIENT_ID, WAYVIA_CONFIG_ID, and WAYVIA_TOKEN for typos or stray whitespace.
• If the issue persists, contact your Wayvia account manager to confirm the credentials are active.

Need to see logs?

macOS:

tail -F ~/Library/Logs/Claude/mcp-server-shoppable.log

Windows:

Get-Content "$env:APPDATA\Claude\logs\mcp-server-shoppable.log" -Wait

Support

For questions or issues, contact your Wayvia account manager or email [email protected].

License

MIT