ShopSavvy Data API MCP Server

1# ShopSavvy Data API MCP Server
2 
3A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that provides AI assistants with access to ShopSavvy's comprehensive product data, pricing information, and historical price tracking.
4 
5## Overview
6 
7This MCP server enables AI assistants to:
8- **Look up products** by barcode, ASIN, URL, model number, or ShopSavvy ID
9- **Get current pricing** from multiple retailers
10- **Access historical pricing data** with date ranges
11- **Schedule products** for automatic price monitoring
12- **Track API usage** and credit consumption
13 
14## Features
15 
16### 🔍 Product Lookup Tools
17- `product_lookup` - Find products by various identifiers (barcode, ASIN, URL, etc.)
18- `product_lookup_batch` - Look up multiple products at once
19 
20### 💰 Pricing Tools
21- `product_offers` - Get current offers from all retailers
22- `product_offers_retailer` - Get offers from a specific retailer
23- `product_price_history` - Get historical pricing data with date ranges
24 
25### 📅 Scheduling Tools
26- `product_schedule` - Schedule products for automatic refresh (hourly/daily/weekly)
27- `product_unschedule` - Remove products from refresh schedule
28- `scheduled_products_list` - View all scheduled products
29 
30### 📊 Analytics Tools
31- `api_usage` - View current API usage and credit consumption
32 
33## Installation
34 
35```bash
36npm install @shopsavvy/mcp-server
37```
38 
39## Configuration
40 
41### 1. Get API Key
42 
43First, get your ShopSavvy Data API key:
44 
451. Visit [https://shopsavvy.com/data](https://shopsavvy.com/data)
462. Sign up and choose a subscription plan
473. Create an API key in your dashboard
484. Copy your API key (starts with `ss_live_` or `ss_test_`)
49 
50### 2. Claude Desktop Setup
51 
52Add this to your Claude Desktop configuration file:
53 
54**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
55**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`
56 
57```json
58{
59  "mcpServers": {
60    "shopsavvy": {
61      "command": "npx",
62      "args": [
63        "@shopsavvy/mcp-server"
64      ],
65      "env": {
66        "SHOPSAVVY_API_KEY": "your_api_key_here"
67      }
68    }
69  }
70}
71```
72 
73### 3. Environment Variables
74 
75Set your API key as an environment variable:
76 
77```bash
78export SHOPSAVVY_API_KEY="ss_live_your_key_here"
79```
80 
81Or create a `.env` file:
82```
83SHOPSAVVY_API_KEY=ss_live_your_key_here
84```
85 
86## Usage Examples
87 
88### Product Lookup
89```
90Look up the product with barcode 012345678901
91```
92 
93### Current Pricing
94```
95Get current prices for ASIN B08N5WRWNW from all retailers
96```
97 
98### Price History
99```
100Get price history for product 012345678901 from January 1-15, 2024
101```
102 
103### Schedule Monitoring
104```
105Schedule daily price monitoring for products: 012345678901, B08N5WRWNW
106```
107 
108## API Limits & Pricing
109 
110- **Starter Plan**: 1,000 credits/month - $49/month
111- **Professional Plan**: 10,000 credits/month - $199/month
112- **Enterprise Plan**: 100,000 credits/month - $499/month
113 
114### Credit Usage:
115- Product lookup: 1 credit per product found
116- Current offers (all retailers): 3 credits per product
117- Current offers (single retailer): 2 credits per product
118- Historical data: 3 credits + 1 credit per day of history
119- Scheduling: 1 credit per product scheduled
120 
121## Development
122 
123### Running Locally
124 
125```bash
126# Clone the repository
127git clone https://github.com/shopsavvy/shopsavvy-mcp-server
128cd shopsavvy-mcp-server
129 
130# Install dependencies
131npm install
132 
133# Set your API key
134export SHOPSAVVY_API_KEY="your_key_here"
135 
136# Test with MCP CLI
137npm run dev
138 
139# Or inspect with MCP Inspector
140npm run inspect
141```
142 
143### Building
144 
145```bash
146npm run build
147```
148 
149## Error Handling
150 
151The server provides detailed error messages for:
152- Invalid API keys
153- Insufficient credits
154- Rate limiting
155- Invalid product identifiers
156- API service issues
157 
158## Support
159 
160- **Documentation**: [https://shopsavvy.com/data/documentation](https://shopsavvy.com/data/documentation)
161- **Dashboard**: [https://shopsavvy.com/data/dashboard](https://shopsavvy.com/data/dashboard)
162- **Issues**: [https://github.com/shopsavvy/shopsavvy-mcp-server/issues](https://github.com/shopsavvy/shopsavvy-mcp-server/issues)
163 
164## Changelog
165 
166### v1.0.0 (2025-07-28)
167 
168🎉 **Initial Release**
169 
170- **Features**: Complete ShopSavvy Data API integration with MCP support
171- **Product Tools**: Lookup by barcode, ASIN, URL, model number, or ShopSavvy ID
172- **Pricing Tools**: Current offers from all/specific retailers, historical pricing data
173- **Scheduling Tools**: Automatic product monitoring (hourly/daily/weekly)
174- **Analytics Tools**: API usage tracking and credit consumption monitoring
175- **npm Package**: Published as `@shopsavvy/mcp-server` under ShopSavvy organization
176- **TypeScript**: Full TypeScript support with proper error handling
177- **Documentation**: Comprehensive README with examples and configuration guides
178 
179## License
180 
181MIT License - see [LICENSE](LICENSE) file for details.
182 
183---
184 
185Made with ❤️ by [ShopSavvy](https://shopsavvy.com) - Empowering everyone to always get the best deal, every time.