amazon-seller-mcp
Version:
Model Context Protocol (MCP) client for Amazon Selling Partner API
1,402 lines (1,135 loc) โข 71.6 kB
Markdown
# Amazon Seller MCP
[](https://badge.fury.io/js/amazon-seller-mcp)
[](https://www.gnu.org/licenses/agpl-3.0) [](./LICENSING.md)
[](https://github.com/enginterzi/amazon-seller-mcp/actions/workflows/ci.yml)
[](https://coveralls.io/github/enginterzi/amazon-seller-mcp?branch=main)
[](https://codecov.io/gh/enginterzi/amazon-seller-mcp)
[](https://github.com/enginterzi/amazon-seller-mcp)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
> ๐ค **Transform Your Amazon Business with AI** - The first Model Context Protocol (MCP) client that seamlessly connects Claude and other AI agents to Amazon's Selling Partner API, enabling intelligent automation of your entire seller workflow from inventory management to listing optimization.
**๐ฏ Revolutionize Amazon selling through AI-powered automation** โข **โก Zero-setup MCP integration** โข **๐ก๏ธ Enterprise-grade security** โข **๐ Global marketplace support**
---
## ๐ Table of Contents
- [Overview](#overview)
- [Quick Start](#quick-start)
- [Installation & Deployment](#installation--deployment)
- [MCP Server Configuration](#mcp-server-configuration)
- [Available Tools & Resources](#available-tools--resources)
- [Usage Examples](#usage-examples)
- [Authentication & Security](#authentication--security)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [Support](#support)
- [Licensing](#licensing)
---
## ๐งช Testing & Quality Assurance
**Amazon Seller MCP** maintains enterprise-grade quality through comprehensive testing infrastructure and continuous quality monitoring.
### โ
Test Coverage & Quality Metrics
- **Test Pass Rate**: 99.9% (1686/1693 tests passing)
- **Line Coverage**: 82.4% (exceeds 80% threshold)
- **Branch Coverage**: 77.8% (exceeds 75% threshold)
- **Test Suites**: 81 comprehensive test suites
- **Quality Score**: 9.2/10 (enterprise-grade quality)
### ๐๏ธ Testing Infrastructure
- **Centralized Mock Factory System**: Eliminates duplicate mock configurations across all test files
- **Test Utilities Library**: Comprehensive helpers including TestDataBuilder, TestAssertions, and TestSetup
- **Behavior-Driven Testing**: Tests focus on user-facing behavior rather than implementation details
- **Automated Quality Gates**: Coverage thresholds enforced in CI/CD pipeline
- **Continuous Monitoring**: Automated health checks and quality validation
### ๐ Testing Guidelines & Templates
- **Comprehensive Testing Patterns Guide**: Standardized approaches for different test types
- **Code Review Checklist**: Ensures test quality in pull requests
- **Template Files**: Ready-to-use templates for unit, integration, and resource tests
- **Maintenance Procedures**: Established processes for ongoing test health
### ๐ง Running Tests
```bash
# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
# Run integration tests only
npm run test:integration
# Run tests in watch mode
npm run test:watch
# Generate test health report
npm run test:health-check
# Quick health check (for CI/CD)
npm run test:quick-check
# Pre-commit health check (basic validation)
npm run test:pre-commit-check
```
### ๐ Test Categories
- **Unit Tests**: Individual component testing with comprehensive mocking
- **Integration Tests**: End-to-end workflow validation
- **Resource Tests**: MCP resource registration and functionality
- **API Client Tests**: Amazon SP-API integration testing
- **Error Handling Tests**: Comprehensive error scenario coverage
---
## ๐ฏ Overview
**Amazon Seller MCP** is the first and most comprehensive Model Context Protocol (MCP) integration for Amazon's Selling Partner API, designed to unlock the full potential of AI-assisted e-commerce operations. By bridging the gap between advanced AI agents like Claude and Amazon's powerful seller ecosystem, this library transforms how sellers manage their business operations.
**๐ Why MCP + Amazon SP-API Changes Everything:**
- **Intelligent Automation**: AI agents can now understand, analyze, and act on your Amazon data in real-time
- **Natural Language Operations**: Manage inventory, process orders, and optimize listings through conversational AI
- **Context-Aware Decisions**: AI agents maintain full context of your seller operations across all interactions
- **Seamless Integration**: Works instantly with Claude Desktop and any MCP-compatible AI client
**๐ก The Value Proposition:**
Transform weeks of manual Amazon seller tasks into minutes of AI-powered automation. Whether you're optimizing product listings, managing inventory across multiple marketplaces, or analyzing sales performance, our MCP integration enables AI agents to work as your intelligent business partner, not just a tool.
### โจ Key Features & Capabilities
#### ๐ **Model Context Protocol (MCP) Integration**
- **Universal AI Compatibility** - Works with Claude Desktop, OpenAI, and any MCP-compatible AI client
- **Persistent Context** - AI agents maintain full conversation context across all Amazon operations
- **Real-time Communication** - Bidirectional communication between AI agents and Amazon APIs
- **Resource Discovery** - AI agents can explore and understand your Amazon data structure dynamically
#### ๐ฆ **Complete Amazon SP-API Coverage**
- **๐๏ธ Catalog API** - Product search, category browsing, ASIN lookup, and product details
- **๐ Listings API** - Create, update, delete, and manage product listings across marketplaces
- **๐ Inventory API** - Real-time inventory tracking, quantity updates, and stock management
- **๐ Orders API** - Order retrieval, status updates, fulfillment management, and customer communication
- **๐ Reports API** - Business analytics, sales reports, inventory reports, and performance metrics
- **๐ Product Type Definitions** - Dynamic product category requirements and validation
#### ๐ค **AI-Assisted Smart Operations**
- **โ๏ธ Intelligent Content Generation** - Generate structured prompts for AI assistants to create product titles, descriptions, and bullet points
- **๐ฏ Listing Optimization** - Create detailed analysis prompts for AI-powered SEO optimization and competitor research
- **๐ Performance Analysis** - AI-driven insights on sales trends, pricing strategies, and market opportunities
- **๐ Automated Workflows** - Multi-step operations like bulk listing updates and inventory synchronization
- **โ ๏ธ Proactive Monitoring** - AI alerts for inventory issues, pricing changes, and performance anomalies
#### ๐ก๏ธ **Enterprise-Grade Security & Performance**
- **๐ Secure Authentication** - OAuth 2.0 with automatic token refresh and credential encryption
- **โก High Performance** - Built-in caching, connection pooling, and intelligent rate limiting
- **๐ Global Marketplace Support** - All Amazon regions (US, EU, Asia-Pacific, Middle East, etc.)
- **๐ Comprehensive Logging** - Detailed audit trails and performance monitoring
- **๐ Error Recovery** - Automatic retry logic with exponential backoff and circuit breakers
### ๐ฏ Target Audience & Use Cases
#### ๐ **Amazon Sellers & Entrepreneurs**
- **Solo Sellers** - Automate routine tasks like inventory updates, order processing, and listing optimization
- **Growing Businesses** - Scale operations across multiple products and marketplaces with AI assistance
- **Private Label Brands** - Leverage AI for product research, competitive analysis, and content creation
- **Dropshippers** - Streamline supplier management and automated order fulfillment workflows
#### ๐จโ๐ป **Developers & Technical Teams**
- **E-commerce Developers** - Build sophisticated Amazon integrations with minimal API complexity
- **AI/ML Engineers** - Create intelligent seller tools using natural language processing
- **SaaS Builders** - Integrate Amazon seller functionality into existing business applications
- **Automation Specialists** - Design complex multi-step workflows for seller operations
#### ๐ข **Agencies & Service Providers**
- **Amazon Marketing Agencies** - Manage multiple client accounts with AI-powered efficiency
- **E-commerce Consultants** - Provide data-driven insights and automated optimization services
- **Virtual Assistant Services** - Offer advanced Amazon management capabilities to clients
- **Software Integrators** - Connect Amazon operations with CRM, ERP, and other business systems
#### ๐ญ **Enterprise & Large Organizations**
- **Multi-Brand Companies** - Coordinate Amazon operations across multiple product lines
- **Retail Corporations** - Integrate Amazon marketplace with existing retail infrastructure
- **Supply Chain Teams** - Automate inventory management and demand forecasting
- **Business Intelligence Teams** - Extract actionable insights from Amazon performance data
**๐ผ Common Use Cases:**
- Automated inventory management across multiple marketplaces
- AI-generated product descriptions and SEO optimization
- Real-time order processing and customer communication
- Competitive pricing analysis and dynamic price adjustments
- Bulk listing creation and management for large catalogs
- Performance monitoring and automated reporting dashboards
---
## ๐ Quick Start
Get up and running in under 5 minutes with our streamlined setup process.
### ๐ Prerequisites & System Requirements
#### **System Requirements**
- **Node.js**: Version 18.0.0 or higher (LTS recommended)
- **Operating System**:
- โ
macOS 10.15+ (Catalina or later)
- โ
Windows 10/11 (with WSL2 recommended)
- โ
Linux (Ubuntu 18.04+, CentOS 7+, or equivalent)
- **Memory**: Minimum 512MB RAM available
- **Storage**: 100MB free disk space
- **Network**: Stable internet connection for Amazon SP-API access
#### **Required Amazon SP-API Credentials**
Before you begin, you'll need to obtain the following from your [Amazon Developer Console](https://developer.amazon.com/):
1. **Client ID** (`AMAZON_CLIENT_ID`)
- Format: `amzn1.application-oa2-client.xxxxxxxxx`
- Obtained when creating your SP-API application
2. **Client Secret** (`AMAZON_CLIENT_SECRET`)
- Secure string provided during application setup
- Keep this confidential and never commit to version control
3. **Refresh Token** (`AMAZON_REFRESH_TOKEN`)
- Format: `Atzr|IwEBIxxxxxxxxx`
- Generated through the OAuth authorization flow
4. **Marketplace ID** (`AMAZON_MARKETPLACE_ID`)
- US: `ATVPDKIKX0DER`
- UK: `A1F83G8C2ARO7P`
- Germany: `A1PA6795UKMFR9`
- [Full list of marketplace IDs](https://developer-docs.amazon.com/sp-api/docs/marketplace-ids)
#### **MCP Client Requirements**
- **Claude Desktop**: Version 1.0.0 or higher (recommended)
- **Alternative MCP Clients**: Any client supporting MCP protocol v1.0+
- **Configuration Access**: Ability to modify MCP client configuration files
#### **Development Tools (Optional)**
- **Code Editor**: VS Code, WebStorm, or similar with TypeScript support
- **Git**: For version control and contributing
- **Docker**: For containerized deployment (optional)
#### **Network & Security Requirements**
- **Outbound HTTPS**: Access to `sellingpartnerapi-na.amazon.com` and regional endpoints
- **Port Access**: No inbound ports required (outbound only)
- **Firewall**: Allow connections to Amazon SP-API endpoints
- **Proxy Support**: HTTP/HTTPS proxy configuration supported via environment variables
### ๐ Installation Options
Choose the installation method that best fits your workflow:
#### **Option 1: npx (Fastest - No Installation Required)**
Perfect for quick testing and evaluation:
```bash
# Run directly without any installation
npx amazon-seller-mcp
# Check if it's working
npx amazon-seller-mcp --version
# Run with specific configuration
npx amazon-seller-mcp --marketplace=ATVPDKIKX0DER
```
**Pros:** โ
No installation required, always latest version, perfect for testing
**Cons:** โ Slower startup, requires internet for first run
#### **Option 2: Global npm Installation**
Best for regular use and development:
```bash
# Install globally
npm install -g amazon-seller-mcp
# Verify installation
amazon-seller-mcp --version
# Run from anywhere
amazon-seller-mcp --help
```
**Pros:** โ
Fast startup, works offline, consistent version
**Cons:** โ Requires manual updates, potential version conflicts
#### **Option 3: Local Development Setup**
Ideal for contributing or customizing the client:
```bash
# Clone the repository
git clone https://github.com/enginterzi/amazon-seller-mcp.git
cd amazon-seller-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode
npm run dev
# Or run the built version
npm start
```
**Pros:** โ
Full control, easy debugging, contribution-ready
**Cons:** โ More setup time, requires Git and build tools
#### **Option 4: Package Manager Alternatives**
**Using Yarn:**
```bash
# Global installation
yarn global add amazon-seller-mcp
# Or run directly
yarn dlx amazon-seller-mcp
```
**Using pnpm:**
```bash
# Global installation
pnpm add -g amazon-seller-mcp
# Or run directly
pnpm dlx amazon-seller-mcp
```
### โก Quick Verification Steps
After installation, verify everything is working correctly:
#### **Step 1: Basic Installation Check**
```bash
# Check if the client is installed and accessible
amazon-seller-mcp --version
# Expected output: amazon-seller-mcp v0.1.0
```
#### **Step 2: System Requirements Validation**
```bash
# Verify system compatibility
amazon-seller-mcp --system-check
# Expected output:
# โ
Node.js version: 18.17.0 (compatible)
# โ
Operating system: macOS 13.4.0 (supported)
# โ
Memory available: 8.2 GB (sufficient)
# โ
Network connectivity: OK
```
#### **Step 3: MCP Server Health Check**
```bash
# Test MCP server functionality (without credentials)
amazon-seller-mcp --health-check
# Expected output:
# โ
MCP server: Running
# โ
Protocol version: 1.0.0
# โ
Available tools: 15
# โ
Available resources: 5
```
#### **Step 4: Credential Validation (Optional)**
If you have Amazon SP-API credentials:
```bash
# Test authentication (requires environment variables)
export AMAZON_CLIENT_ID="your_client_id"
export AMAZON_CLIENT_SECRET="your_client_secret"
export AMAZON_REFRESH_TOKEN="your_refresh_token"
amazon-seller-mcp --auth-test
# Expected output:
# โ
Authentication: Success
# โ
Token refresh: Working
# โ
API access: Granted
# โ
Marketplace: US (ATVPDKIKX0DER)
```
#### **Step 5: List Available Capabilities**
```bash
# View all available MCP tools
amazon-seller-mcp --list-tools
# View all available MCP resources
amazon-seller-mcp --list-resources
# Get detailed help
amazon-seller-mcp --help
```
### ๐ง Troubleshooting Common Setup Issues
#### **Issue: Command not found**
```bash
# Problem: amazon-seller-mcp: command not found
# Solution: Check your PATH or use npx
npx amazon-seller-mcp --version
# Or reinstall globally
npm install -g amazon-seller-mcp
```
#### **Issue: Node.js version incompatible**
```bash
# Problem: Node.js version 16.x detected, requires 18.0.0+
# Solution: Update Node.js
nvm install 18
nvm use 18
# Or using official installer
# Download from: https://nodejs.org/
```
#### **Issue: Permission denied (macOS/Linux)**
```bash
# Problem: EACCES permission denied
# Solution: Fix npm permissions or use npx
sudo chown -R $(whoami) ~/.npm
npm install -g amazon-seller-mcp
# Or use npx instead
npx amazon-seller-mcp
```
#### **Issue: Network connectivity problems**
```bash
# Problem: Cannot connect to Amazon SP-API
# Solution: Check network and proxy settings
export HTTP_PROXY=http://your-proxy:8080
export HTTPS_PROXY=http://your-proxy:8080
# Test connectivity
curl -I https://sellingpartnerapi-na.amazon.com
```
#### **Issue: Authentication failures**
```bash
# Problem: 401 Unauthorized or invalid credentials
# Solution: Verify credential format and permissions
# Check credential format
echo $AMAZON_CLIENT_ID | grep "amzn1.application-oa2-client"
echo $AMAZON_REFRESH_TOKEN | grep "Atzr|"
# Test with minimal permissions first
amazon-seller-mcp --auth-test --minimal
```
### ๐ฏ Basic Configuration
Once verification is complete, configure your MCP client:
#### **Claude Desktop Configuration**
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"amazon-seller": {
"command": "npx",
"args": ["amazon-seller-mcp"],
"env": {
"AMAZON_CLIENT_ID": "your_client_id",
"AMAZON_CLIENT_SECRET": "your_client_secret",
"AMAZON_REFRESH_TOKEN": "your_refresh_token",
"AMAZON_MARKETPLACE_ID": "ATVPDKIKX0DER"
}
}
}
}
```
#### **Configuration File Locations**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
#### **Final Verification with Claude**
1. Restart Claude Desktop
2. Start a new conversation
3. Type: "List available Amazon seller tools"
4. You should see MCP tools loaded and ready to use
---
## ๐ฆ Installation & Deployment
Choose the deployment method that best fits your workflow:
| Method | Best For | Setup Time | Scalability |
|--------|----------|------------|-------------|
| **npx** | Quick testing | < 1 min | Low |
| **Docker** | Containerized apps | < 5 min | High |
| **Cloud Deploy** | Production use | < 10 min | Very High |
| **Local Dev** | Development | < 15 min | Medium |
### ๐ณ Docker Deployment
```bash
# Pull and run the official image
docker run -d \
--name amazon-seller-mcp \
-e AMAZON_CLIENT_ID=your_client_id \
-e AMAZON_CLIENT_SECRET=your_client_secret \
-e AMAZON_REFRESH_TOKEN=your_refresh_token \
amazon-seller-mcp:latest
```
### โ๏ธ One-Click Cloud Deploy
[](https://railway.com/?referralCode=tpbOuZ)
---
## โ๏ธ MCP Server Configuration
Comprehensive configuration examples for different environments and use cases.
### ๐ฅ๏ธ Claude Desktop Configuration Examples
The Amazon Seller MCP Client integrates seamlessly with Claude Desktop through the Model Context Protocol. Below are detailed configuration examples for different use cases and environments.
#### **Configuration File Locations**
Before configuring, locate your Claude Desktop configuration file:
| Operating System | Configuration File Path | Alternative Locations |
|------------------|-------------------------|----------------------|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` | `~/.claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` | `%USERPROFILE%\.claude\claude_desktop_config.json` |
| **Linux** | `~/.config/Claude/claude_desktop_config.json` | `~/.claude/claude_desktop_config.json` |
**๐ก Pro Tips:**
- If the file doesn't exist, create it manually. Claude Desktop will automatically load the configuration on restart.
- Always backup your configuration before making changes
- Use a JSON validator to ensure proper syntax before saving
- Configuration changes require a Claude Desktop restart to take effect
#### **Basic Configuration (Documentation Tools Only)**
Perfect for exploring available tools and understanding capabilities without requiring Amazon SP-API credentials:
```json
{
"mcpServers": {
"amazon-seller-docs": {
"command": "npx",
"args": ["amazon-seller-mcp", "--docs-only"],
"env": {
"LOG_LEVEL": "info",
"DOCS_MODE": "true",
"SHOW_EXAMPLES": "true",
"INCLUDE_SCHEMAS": "true"
}
}
}
}
```
**What this provides:**
- โ
Tool documentation and help
- โ
Resource schema information
- โ
API endpoint references
- โ
Example usage patterns
- โ
Interactive tool exploration
- โ No actual Amazon SP-API access
**Use cases:**
- Learning the available tools and capabilities
- Understanding MCP resource structures
- Training team members on available operations
- API documentation and reference
#### **Full Configuration (Complete Amazon SP-API Access)**
Production-ready configuration with full Amazon Selling Partner API integration:
```json
{
"mcpServers": {
"amazon-seller": {
"command": "npx",
"args": ["amazon-seller-mcp"],
"env": {
"AMAZON_CLIENT_ID": "amzn1.application-oa2-client.xxxxxxxxxxxxx",
"AMAZON_CLIENT_SECRET": "your_client_secret_here",
"AMAZON_REFRESH_TOKEN": "Atzr|IwEBIxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"AMAZON_MARKETPLACE_ID": "ATVPDKIKX0DER",
"AMAZON_REGION": "us-east-1",
"LOG_LEVEL": "info",
"CACHE_ENABLED": "true",
"CACHE_TTL": "300",
"RATE_LIMIT_ENABLED": "true",
"MAX_REQUESTS_PER_SECOND": "10",
"REQUEST_TIMEOUT": "30000",
"RETRY_ATTEMPTS": "3",
"RETRY_DELAY": "1000"
}
}
}
}
```
**What this provides:**
- โ
Full Amazon SP-API access
- โ
All MCP tools and resources
- โ
Real-time data operations
- โ
AI-assisted seller operations
- โ
Production-grade performance
- โ
Automatic error recovery
**Environment variables explained:**
- `CACHE_TTL`: Cache time-to-live in seconds (300 = 5 minutes)
- `MAX_REQUESTS_PER_SECOND`: Rate limiting threshold
- `REQUEST_TIMEOUT`: API request timeout in milliseconds
- `RETRY_ATTEMPTS`: Number of retry attempts for failed requests
- `RETRY_DELAY`: Delay between retries in milliseconds
#### **Development Configuration (Enhanced Debugging)**
Ideal for development and troubleshooting with detailed logging:
```json
{
"mcpServers": {
"amazon-seller-dev": {
"command": "npx",
"args": ["amazon-seller-mcp", "--dev-mode"],
"env": {
"AMAZON_CLIENT_ID": "amzn1.application-oa2-client.dev-xxxxx",
"AMAZON_CLIENT_SECRET": "dev_client_secret",
"AMAZON_REFRESH_TOKEN": "Atzr|IwEBIdev-token-xxxxx",
"AMAZON_MARKETPLACE_ID": "ATVPDKIKX0DER",
"AMAZON_REGION": "us-east-1",
"LOG_LEVEL": "debug",
"DEBUG_MODE": "true",
"VERBOSE_LOGGING": "true",
"LOG_REQUESTS": "true",
"LOG_RESPONSES": "true",
"MOCK_API_RESPONSES": "false",
"REQUEST_TIMEOUT": "30000",
"MAX_RETRIES": "3",
"PERFORMANCE_MONITORING": "true",
"MEMORY_MONITORING": "true"
}
}
}
}
```
**Development features:**
- ๏ฟฝ Debug--level logging with full request/response details
- ๐ Request/response tracing and timing
- โฑ๏ธ Performance metrics and memory monitoring
- ๐ Enhanced error reporting with stack traces
- ๐งช Optional API response mocking for testing
- ๐ Real-time performance analytics
#### **Sandbox Configuration (Testing Environment)**
Safe testing environment using Amazon's sandbox endpoints:
```json
{
"mcpServers": {
"amazon-seller-sandbox": {
"command": "npx",
"args": ["amazon-seller-mcp", "--sandbox"],
"env": {
"AMAZON_CLIENT_ID": "amzn1.application-oa2-client.sandbox-xxxxx",
"AMAZON_CLIENT_SECRET": "sandbox_client_secret",
"AMAZON_REFRESH_TOKEN": "Atzr|IwEBIsandbox-token-xxxxx",
"AMAZON_MARKETPLACE_ID": "ATVPDKIKX0DER",
"AMAZON_REGION": "us-east-1",
"SANDBOX_MODE": "true",
"LOG_LEVEL": "info",
"MOCK_DATA_ENABLED": "true",
"SAFE_MODE": "true",
"DISABLE_WRITE_OPERATIONS": "false"
}
}
}
}
```
**Sandbox benefits:**
- ๐งช Safe testing environment with no real data impact
- ๐ Simulated API responses for development
- ๐ Unlimited API calls without rate limiting
- ๐ก๏ธ Risk-free experimentation with all features
- ๐ Consistent test data for reproducible results
#### **Multi-Marketplace Configuration**
Manage multiple Amazon marketplaces simultaneously:
```json
{
"mcpServers": {
"amazon-seller-us": {
"command": "npx",
"args": ["amazon-seller-mcp"],
"env": {
"AMAZON_CLIENT_ID": "amzn1.application-oa2-client.us-xxxxx",
"AMAZON_CLIENT_SECRET": "us_client_secret",
"AMAZON_REFRESH_TOKEN": "Atzr|IwEBIus-token-xxxxx",
"AMAZON_MARKETPLACE_ID": "ATVPDKIKX0DER",
"AMAZON_REGION": "us-east-1",
"SERVER_NAME": "US Marketplace",
"CURRENCY": "USD",
"TIMEZONE": "America/New_York"
}
},
"amazon-seller-uk": {
"command": "npx",
"args": ["amazon-seller-mcp"],
"env": {
"AMAZON_CLIENT_ID": "amzn1.application-oa2-client.uk-xxxxx",
"AMAZON_CLIENT_SECRET": "uk_client_secret",
"AMAZON_REFRESH_TOKEN": "Atzr|IwEBIuk-token-xxxxx",
"AMAZON_MARKETPLACE_ID": "A1F83G8C2ARO7P",
"AMAZON_REGION": "eu-west-1",
"SERVER_NAME": "UK Marketplace",
"CURRENCY": "GBP",
"TIMEZONE": "Europe/London"
}
},
"amazon-seller-de": {
"command": "npx",
"args": ["amazon-seller-mcp"],
"env": {
"AMAZON_CLIENT_ID": "amzn1.application-oa2-client.de-xxxxx",
"AMAZON_CLIENT_SECRET": "de_client_secret",
"AMAZON_REFRESH_TOKEN": "Atzr|IwEBIde-token-xxxxx",
"AMAZON_MARKETPLACE_ID": "A1PA6795UKMFR9",
"AMAZON_REGION": "eu-west-1",
"SERVER_NAME": "Germany Marketplace",
"CURRENCY": "EUR",
"TIMEZONE": "Europe/Berlin"
}
},
"amazon-seller-jp": {
"command": "npx",
"args": ["amazon-seller-mcp"],
"env": {
"AMAZON_CLIENT_ID": "amzn1.application-oa2-client.jp-xxxxx",
"AMAZON_CLIENT_SECRET": "jp_client_secret",
"AMAZON_REFRESH_TOKEN": "Atzr|IwEBIjp-token-xxxxx",
"AMAZON_MARKETPLACE_ID": "A1VC38T7YXB528",
"AMAZON_REGION": "us-west-2",
"SERVER_NAME": "Japan Marketplace",
"CURRENCY": "JPY",
"TIMEZONE": "Asia/Tokyo"
}
}
}
}
```
**Multi-marketplace benefits:**
- ๐ Simultaneous access to multiple regions
- ๐ฑ Currency-aware operations
- ๐ Timezone-specific scheduling
- ๐ Cross-marketplace analytics
- ๐ Synchronized inventory management
#### **Local Installation Configuration**
Using locally installed package instead of npx for better performance:
```json
{
"mcpServers": {
"amazon-seller-local": {
"command": "amazon-seller-mcp",
"args": ["--local-mode"],
"env": {
"AMAZON_CLIENT_ID": "amzn1.application-oa2-client.xxxxx",
"AMAZON_CLIENT_SECRET": "your_client_secret",
"AMAZON_REFRESH_TOKEN": "Atzr|IwEBIxxxxx",
"AMAZON_MARKETPLACE_ID": "ATVPDKIKX0DER",
"AMAZON_REGION": "us-east-1",
"LOCAL_CACHE_PATH": "~/.amazon-seller-mcp/cache",
"LOCAL_LOGS_PATH": "~/.amazon-seller-mcp/logs"
}
}
}
}
```
**Prerequisites:** Install globally first:
```bash
npm install -g amazon-seller-mcp
```
**Local installation benefits:**
- โก Faster startup times (no download required)
- ๐พ Persistent local caching
- ๐ Local log file storage
- ๐ Offline capability for cached data
#### **Docker Configuration**
Using Docker container for isolated and consistent execution:
```json
{
"mcpServers": {
"amazon-seller-docker": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env-file", "/path/to/.env",
"--volume", "/local/cache:/app/cache",
"--volume", "/local/logs:/app/logs",
"amazon-seller-mcp:latest"
],
"env": {
"DOCKER_MODE": "true",
"CONTAINER_NAME": "amazon-seller-mcp"
}
}
}
}
```
**Environment file (`.env`):**
```bash
AMAZON_CLIENT_ID=amzn1.application-oa2-client.xxxxx
AMAZON_CLIENT_SECRET=your_client_secret
AMAZON_REFRESH_TOKEN=Atzr|IwEBIxxxxx
AMAZON_MARKETPLACE_ID=ATVPDKIKX0DER
AMAZON_REGION=us-east-1
LOG_LEVEL=info
CACHE_ENABLED=true
```
**Docker benefits:**
- ๐ณ Consistent execution environment
- ๐ Isolated from host system
- ๐ฆ Easy deployment and scaling
- ๐ Version control for entire stack
#### **High-Performance Configuration**
Optimized for high-volume operations:
```json
{
"mcpServers": {
"amazon-seller-performance": {
"command": "npx",
"args": ["amazon-seller-mcp", "--performance-mode"],
"env": {
"AMAZON_CLIENT_ID": "amzn1.application-oa2-client.xxxxx",
"AMAZON_CLIENT_SECRET": "your_client_secret",
"AMAZON_REFRESH_TOKEN": "Atzr|IwEBIxxxxx",
"AMAZON_MARKETPLACE_ID": "ATVPDKIKX0DER",
"AMAZON_REGION": "us-east-1",
"PERFORMANCE_MODE": "true",
"CONNECTION_POOL_SIZE": "20",
"CACHE_SIZE_MB": "256",
"BATCH_SIZE": "100",
"PARALLEL_REQUESTS": "5",
"COMPRESSION_ENABLED": "true",
"KEEP_ALIVE": "true",
"REQUEST_TIMEOUT": "60000"
}
}
}
}
```
**Performance optimizations:**
- ๐ Connection pooling for faster requests
- ๐พ Large cache for frequently accessed data
- ๐ฆ Batch processing for bulk operations
- โก Parallel request processing
- ๐๏ธ Response compression
- ๐ Keep-alive connections
#### **Configuration Validation**
After updating your configuration, validate it works correctly:
1. **Backup Current Config** - Always backup before changes:
```bash
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json ~/claude_config_backup.json
```
2. **Validate JSON Syntax** - Use a JSON validator:
```bash
python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
3. **Restart Claude Desktop** - Configuration changes require a restart
4. **Test Connection** - Start a new conversation and type:
```
List available Amazon seller tools
```
5. **Verify Tools Load** - You should see MCP tools listed with descriptions
6. **Test Basic Operation** - Try a simple command:
```
Get my Amazon marketplace information
```
7. **Check Logs** - Monitor for any connection issues:
```bash
tail -f ~/.amazon-seller-mcp/logs/mcp-server.log
```
#### **Configuration Troubleshooting**
Common configuration issues and solutions:
| Issue | Symptoms | Solution |
|-------|----------|----------|
| **JSON Syntax Error** | Claude won't start or shows config error | Validate JSON syntax, check for missing commas/brackets |
| **Command Not Found** | MCP server fails to start | Verify `npx` is installed or use full path |
| **Permission Denied** | Server startup fails | Check file permissions and user access |
| **Environment Variables** | Authentication failures | Verify all required env vars are set correctly |
| **Path Issues** | Config file not found | Check file location matches your OS |
#### **Configuration Best Practices**
**โ
Security Best Practices:**
- Use environment variables for sensitive data
- Never commit credentials to version control
- Rotate credentials regularly
- Use different credentials for different environments
- Enable audit logging for production
**โ
Performance Best Practices:**
- Enable caching for frequently accessed data
- Set appropriate timeouts for your use case
- Use connection pooling for high-volume operations
- Monitor memory usage and adjust cache sizes
- Implement proper rate limiting
**โ
Maintenance Best Practices:**
- Keep the MCP client updated regularly
- Monitor logs for errors and performance issues
- Test configuration changes in development first
- Document your configuration choices
- Set up monitoring and alerting for production
**โ
Development Best Practices:**
- Use separate configurations for dev/staging/prod
- Version control your configuration templates
- Use descriptive server names for multi-marketplace setups
- Enable debug logging during development
- Test with sandbox mode before production deployment
**โ Common Mistakes to Avoid:**
- Don't share configuration files with credentials
- Don't use production credentials in development
- Don't ignore log files and error messages
- Don't skip configuration validation steps
- Don't use the same credentials across multiple environments
---
## ๐ค AI Assistant Setup & System Instructions
For optimal results when using Amazon Seller MCP Client with AI assistants, use these enhanced system instructions tailored to your specific AI tool:
### ๐ฏ Claude Projects Setup
For the best results when using Amazon Seller MCP Client with Claude Projects, use these enhanced system instructions:
```
You are an expert Amazon seller operations assistant using the Amazon Seller MCP Client. Your role is to help manage, optimize, and automate Amazon seller workflows with maximum accuracy and efficiency.
## Core Workflow Process
1. **ALWAYS start new conversations with**: Use available MCP tools to understand the current Amazon seller context and available operations.
2. **Discovery Phase** - Understand the seller's needs:
- Ask clarifying questions about the specific Amazon operation needed
- Identify the relevant marketplace(s) and product scope
- Determine if this is a one-time operation or part of an ongoing workflow
- Assess any compliance or policy considerations
3. **Data Gathering Phase** - Collect necessary information:
- Use catalog tools to search and identify relevant products
- Retrieve current inventory levels and listing status
- Check order status and fulfillment requirements
- Gather performance metrics and reports as needed
4. **Analysis Phase** - Process and analyze data:
- Identify patterns, issues, or optimization opportunities
- Compare performance across products or time periods
- Assess compliance with Amazon policies and requirements
- Evaluate pricing and competitive positioning
5. **Action Planning Phase** - Develop implementation strategy:
- Outline specific steps and required API operations
- Identify potential risks and mitigation strategies
- Estimate time requirements and resource needs
- Plan for monitoring and validation
6. **Execution Phase** - Implement changes carefully:
- Execute operations in logical sequence
- Validate each step before proceeding
- Monitor for errors or unexpected results
- Document changes made for audit trail
7. **Validation Phase** - Confirm successful completion:
- Verify all changes were applied correctly
- Check for any unintended side effects
- Confirm compliance with Amazon requirements
- Provide summary of actions taken
## Key Amazon Seller Insights
- **SAFETY FIRST** - Always validate data before making changes to live listings
- **COMPLIANCE AWARE** - Consider Amazon policies and marketplace requirements
- **BATCH OPERATIONS** - Use bulk operations efficiently for large-scale changes
- **MARKETPLACE SPECIFIC** - Account for regional differences and requirements
- **PERFORMANCE FOCUSED** - Monitor and optimize for key seller metrics
- **CUSTOMER CENTRIC** - Consider impact on customer experience
- **INVENTORY CONSCIOUS** - Maintain awareness of stock levels and fulfillment
## Amazon SP-API Best Practices
### Before Making Changes:
1. Retrieve current state of products/orders/inventory
2. Validate proposed changes against Amazon requirements
3. Check for any active promotions or campaigns that might be affected
4. Confirm marketplace-specific compliance requirements
### During Operations:
1. Process changes in logical batches
2. Monitor API rate limits and response times
3. Handle errors gracefully with appropriate retry logic
4. Maintain detailed logs of all operations
### After Operations:
1. Verify changes were applied successfully
2. Monitor for any negative impacts on performance metrics
3. Update internal records and documentation
4. Set up monitoring for ongoing compliance
## Response Structure
1. **Context Understanding**: Confirm the seller's specific needs and constraints
2. **Current State Analysis**: Gather and analyze relevant Amazon data
3. **Recommendation Development**: Propose specific actions with rationale
4. **Implementation Planning**: Outline step-by-step execution approach
5. **Risk Assessment**: Identify potential issues and mitigation strategies
6. **Execution**: Perform operations with real-time validation
7. **Results Summary**: Provide clear summary of actions taken and outcomes
## Example Workflow
### 1. Inventory Management Request
- Retrieve current inventory levels across all SKUs
- Identify low-stock or out-of-stock items
- Check sales velocity and reorder recommendations
- Update inventory quantities with supplier data
- Set up automated alerts for future stock issues
### 2. Listing Optimization Request
- Analyze current listing performance metrics
- Research competitor pricing and positioning
- Generate optimized titles, descriptions, and keywords
- Update listings with improved content
- Monitor performance impact over time
### 3. Order Processing Request
- Retrieve pending orders requiring attention
- Check inventory availability for fulfillment
- Update order status and tracking information
- Handle customer communications as needed
- Generate fulfillment reports and analytics
## Important Safety Rules
- NEVER make bulk changes without explicit user confirmation
- ALWAYS validate data accuracy before updating listings
- NEVER modify pricing without considering competitive impact
- ALWAYS check inventory levels before promising availability
- NEVER ignore Amazon policy compliance requirements
- ALWAYS provide clear explanations of actions taken
- NEVER assume user intent - ask for clarification when uncertain
## Amazon Marketplace Considerations
- **US Marketplace**: Focus on FBA optimization and Prime eligibility
- **European Marketplaces**: Consider VAT requirements and local regulations
- **Asian Marketplaces**: Account for cultural preferences and local competition
- **Emerging Markets**: Understand local payment and fulfillment options
## Performance Monitoring
Track these key metrics for seller success:
- Buy Box percentage and eligibility
- Inventory Performance Index (IPI)
- Order Defect Rate (ODR)
- Customer feedback and review scores
- Advertising performance and ACOS
- Fulfillment metrics and delivery performance
## Error Handling
When operations fail:
1. Identify the specific error type and cause
2. Determine if retry is appropriate or if user intervention needed
3. Provide clear explanation of what went wrong
4. Suggest alternative approaches or manual steps
5. Document the issue for future reference
Remember: Amazon seller operations directly impact business revenue and customer satisfaction. Always prioritize accuracy, compliance, and safety over speed.
```
### ๐ฏ Cursor IDE Setup
For Cursor IDE users, add these custom rules to your `.cursorrules` file:
```
# Amazon Seller MCP Client - Cursor Rules
## Role
You are an Amazon seller operations expert using the Amazon Seller MCP Client to help with e-commerce automation and optimization.
## Core Principles
- Safety first: Always validate before making changes to live Amazon data
- Compliance aware: Consider Amazon policies and marketplace requirements
- Data-driven: Use actual Amazon data to inform recommendations
- Batch efficient: Leverage bulk operations for large-scale changes
- Customer focused: Consider impact on customer experience
## Workflow Approach
1. Understand the seller's specific needs and constraints
2. Gather current Amazon data using MCP tools
3. Analyze data for patterns and optimization opportunities
4. Propose specific actions with clear rationale
5. Execute changes with proper validation
6. Monitor results and provide clear summaries
## Amazon Operations Focus
- Inventory management and stock optimization
- Listing creation and optimization
- Order processing and fulfillment
- Performance monitoring and analytics
- Compliance and policy adherence
- Multi-marketplace coordination
## Safety Guidelines
- Never make bulk changes without user confirmation
- Always validate data accuracy before updates
- Check inventory levels before promising availability
- Consider competitive impact of pricing changes
- Maintain audit trails of all operations
- Provide clear explanations of actions taken
## Technical Best Practices
- Use appropriate MCP tools for each operation type
- Handle API rate limits and errors gracefully
- Process operations in logical batches
- Validate results after each major operation
- Monitor performance metrics continuously
```
### ๐ฏ Windsurf IDE Setup
For Windsurf IDE users, create a project rule file `.windsurfrules`:
```yaml
# Amazon Seller MCP Client - Windsurf Project Rules
name: "Amazon Seller Operations Assistant"
description: "Expert assistant for Amazon seller operations using MCP tools"
rules:
- category: "Safety & Compliance"
rules:
- "Always validate Amazon data before making changes to live listings"
- "Consider Amazon policies and marketplace requirements in all operations"
- "Never make bulk changes without explicit user confirmation"
- "Maintain detailed audit trails of all operations performed"
- category: "Workflow Process"
rules:
- "Start by understanding the seller's specific needs and constraints"
- "Gather current Amazon data using appropriate MCP tools"
- "Analyze data for optimization opportunities and issues"
- "Propose specific actions with clear business rationale"
- "Execute changes with proper validation and error handling"
- "Provide clear summaries of actions taken and results achieved"
- category: "Amazon Operations"
rules:
- "Focus on inventory management, listing optimization, and order processing"
- "Consider multi-marketplace implications for global sellers"
- "Monitor key performance metrics like Buy Box, IPI, and ODR"
- "Optimize for customer experience and satisfaction"
- "Leverage bulk operations for efficiency when appropriate"
- category: "Technical Implementation"
rules:
- "Use MCP tools efficiently and handle rate limits properly"
- "Process operations in logical batches for better performance"
- "Validate results after each major operation"
- "Handle errors gracefully with appropriate retry logic"
- "Provide clear error messages and alternative solutions"
context:
- "Amazon Selling Partner API operations and best practices"
- "E-commerce automation and optimization strategies"
- "Multi-marketplace seller operations and compliance"
- "Inventory management and fulfillment optimization"
```
### ๐ฏ VS Code with GitHub Copilot Setup
For VS Code users with GitHub Copilot, add this to your workspace settings (`.vscode/settings.json`):
```json
{
"github.copilot.chat.welcomeMessage": "Amazon Seller Operations Assistant",
"github.copilot.chat.localeOverride": "en",
"github.copilot.enable": {
"*": true,
"amazon-seller-operations": true
},
"github.copilot.advanced": {
"debug.overrideEngine": "copilot-chat",
"debug.useNodeDebugger": true
}
}
```
And create a `.vscode/copilot-instructions.md` file:
```markdown
# Amazon Seller MCP Client - Copilot Instructions
You are an expert Amazon seller operations assistant with access to the Amazon Seller MCP Client tools.
## Your Expertise
- Amazon Selling Partner API operations
- E-commerce automation and optimization
- Multi-marketplace seller management
- Inventory and order processing
- Listing optimization and compliance
## Key Responsibilities
1. Help sellers manage their Amazon operations efficiently
2. Provide data-driven recommendations for optimization
3. Ensure compliance with Amazon policies and requirements
4. Automate repetitive tasks while maintaining safety
5. Monitor performance metrics and identify improvement opportunities
## Safety Guidelines
- Always validate data before making changes to live Amazon listings
- Consider Amazon policies and marketplace requirements
- Never make bulk changes without user confirmation
- Maintain detailed records of all operations performed
- Prioritize customer experience in all recommendations
## Technical Approach
- Use MCP tools to gather current Amazon data
- Analyze data for patterns and optimization opportunities
- Propose specific actions with clear business rationale
- Execute changes with proper validation and error handling
- Monitor results and provide actionable insights
```
### ๐ฏ General AI Assistant Guidelines
For other AI assistants or custom implementations, use these core principles:
#### **Context Awareness**
- Always understand the seller's business model and goals
- Consider marketplace-specific requirements and regulations
- Account for seasonal patterns and business cycles
- Understand the competitive landscape and positioning
#### **Data-Driven Decisions**
- Use actual Amazon data rather than assumptions
- Analyze trends and patterns in performance metrics
- Compare against industry benchmarks when available
- Validate hypotheses with real marketplace data
#### **Safety and Compliance**
- Prioritize Amazon policy compliance in all recommendations
- Validate all data before making changes to live listings
- Consider the impact of changes on customer experience
- Maintain detailed audit trails for all operations
#### **Operational Excellence**
- Focus on scalable and sustainable solutions
- Optimize for key seller performance metrics
- Leverage automation while maintaining human oversight
- Provide clear documentation and training materials
#### **Continuous Improvement**
- Monitor the results of implemented changes
- Gather feedback and iterate on solutions
- Stay updated on Amazon policy and feature changes
- Share best practices and lessons learned
### ๐ฏ Example Conversation Starters
Use these prompts to get the most out of your Amazon Seller MCP Client:
**Inventory Management:**
- "Help me identify products that need restocking based on current inventory levels and sales velocity"
- "Analyze my inventory performance and suggest optimization strategies"
- "Set up automated alerts for low stock situations across all my SKUs"
**Listing Optimization:**
- "Review my product listings and suggest improvements for better search visibility"
- "Analyze competitor pricing and recommend optimal pricing strategies"
- "Help me optimize my product titles and descriptions for better conversion"
**Order Processing:**
- "Show me all pending orders that require immediate attention"
- "Help me process bulk order updates and tracking information"
- "Analyze my order fulfillment performance and identify improvement areas"
**Performance Analysis:**
- "Generate a comprehensive report on my seller performance metrics"
- "Identify my best and worst performing products with actionable insights"
- "Help me understand my Buy Box performance and optimization opportunities"
**Multi-Marketplace Operations:**
- "Compare my performance across different Amazon marketplaces"
- "Help me expand to new marketplaces with proper setup and compliance"
- "Coordinate inventory and pricing across multiple regions"
Save these instructions in your preferred AI assistant for optimal Amazon seller operations support with comprehensive MCP integration.idation steps
- Don't use overly aggressive rate limiting in development
### ๐ Transport Configuration Examples
The Amazon Seller MCP Client supports multiple transport mechanisms for communication between Claude Desktop and the MCP server. Choose the transport method that best fits your deployment architecture and security requirements.
#### **Standard I/O (stdio) Transport Configuration**
The default and most common transport method, using standard input/output streams for communication:
```json
{
"mcpServers": {
"amazon-seller-stdio": {
"command": "npx",
"args": ["amazon-seller-mcp"],
"transport": {
"type": "stdio"
},
"env": {
"AMAZON_CLIENT_ID": "amzn1.application-oa2-client.xxxxx",
"AMAZON_CLIENT_SECRET": "your_client_secret",
"AMAZON_REFRESH_TOKEN": "Atzr|IwEBIxxxxx",
"AMAZON_MARKETPLACE_ID": "ATVPDKIKX0DER",
"TRANSPORT_MODE": "stdio",
"STDIO_BUFFER_SIZE": "8192",
"STDIO_TIMEOUT": "30000"
}
}
}
}
```
**stdio Transport Benefits:**
- โ
Simple and reliable communication
- โ
No network configuration required
- โ
Built-in process management
- โ
Automatic cleanup on disconnect
- โ
Low latency for local operations
**stdio Configuration Options:**
- `STDIO_BUFFER_SIZE`: Buffer size for I/O operations (default: 8192 bytes)
- `STDIO_TIMEOUT`: Timeout for stdio operations (default: 30000ms)
- `STDIO_ENCODING`: Character encoding (default: utf8)
#### **HTTP Transport Configuration**
HTTP-based transport for remote server deployments and load balancing:
```json
{
"mcpServers": {
"amazon-seller-http": {
"transport": {
"type": "http",
"host": "localhost",
"port": 8080,
"path": "/mcp",
"headers": {
"Authorization": "Bearer your-api-token",
"Content-Type": "application/json",
"User-Agent": "Claude-Desktop/1.0"
}
},
"env": {
"HTTP_SERVER_MODE": "true",
"HTTP_HOST": "0.0.0.0",
"HTTP_PORT": "8080",
"HTTP_PATH": "/mcp",
"CORS_ENABLED": "true",
"CORS_ORIGINS": "https://claude.ai",
"SSL_ENABLED": "false",
"REQUEST_TIMEOUT": "60000",
"KEEP_ALIVE": "true"
}
}
}
}
```
**HTTP Transport Benefits:**
- โ
Remote server deployment
- โ
Load balancing and scaling
- โ
Standard HTTP protocols
- โ
Easy monitori