Model Context Protocol (MCP) client for Amazon Selling Partner API
npm install amazon-seller-mcp
 






> ๐ค 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
---
- Overview
- Quick Start
- Installation & Deployment
- MCP Server Configuration
- Available Tools & Resources
- Usage Examples
- Authentication & Security
- Troubleshooting
- Contributing
- Support
- Licensing
---
Amazon Seller MCP maintains enterprise-grade quality through comprehensive testing infrastructure and continuous quality monitoring.
``bashRun all tests
npm test
$3
- 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.
$3
#### ๐ 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
$3
#### ๐ 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.
$3
#### 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:
1. Client ID (
AMAZON_CLIENT_ID)
- Format: amzn1.application-oa2-client.xxxxxxxxx
- Obtained when creating your SP-API application2. Client Secret (
AMAZON_CLIENT_SECRET)
- Secure string provided during application setup
- Keep this confidential and never commit to version control3. Refresh Token (
AMAZON_REFRESH_TOKEN)
- Format: Atzr|IwEBIxxxxxxxxx
- Generated through the OAuth authorization flow4. Marketplace ID (
AMAZON_MARKETPLACE_ID)
- US: ATVPDKIKX0DER
- UK: A1F83G8C2ARO7P
- Germany: A1PA6795UKMFR9
- Full list of 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$3
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-mcpCheck if it's working
npx amazon-seller-mcp --versionRun 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-mcpVerify installation
amazon-seller-mcp --versionRun 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-mcpInstall dependencies
npm installBuild the project
npm run buildRun in development mode
npm run devOr 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-mcpOr run directly
yarn dlx amazon-seller-mcp
`Using pnpm:
`bash
Global installation
pnpm add -g amazon-seller-mcpOr run directly
pnpm dlx amazon-seller-mcp
`$3
After installation, verify everything is working correctly:
#### Step 1: Basic Installation Check
`bash
Check if the client is installed and accessible
amazon-seller-mcp --versionExpected output: amazon-seller-mcp v0.1.0
`#### Step 2: System Requirements Validation
`bash
Verify system compatibility
amazon-seller-mcp --system-checkExpected 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-checkExpected 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-toolsView all available MCP resources
amazon-seller-mcp --list-resourcesGet detailed help
amazon-seller-mcp --help
`$3
#### Issue: Command not found
`bash
Problem: amazon-seller-mcp: command not found
Solution: Check your PATH or use npx
npx amazon-seller-mcp --versionOr 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 18Or 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-mcpOr 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:8080Test 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
`$3
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 |
$3
`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
`$3

---
โ๏ธ MCP Server Configuration
Comprehensive configuration examples for different environments and use cases.
$3
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:
$3
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
$3
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$3
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$3
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 complianceResponse 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
$3
- 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$3
- 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
- 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 analyticsImportant 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.
`$3
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 experienceWorkflow 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 summariesAmazon 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 coordinationSafety 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 takenTechnical 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
`$3
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"
`$3
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 complianceKey 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 opportunitiesSafety 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 recommendationsTechnical 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
`$3
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
$3
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
$3
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 monitoring and logging
- โ
Firewall-friendly
HTTP Configuration Options:
-
HTTP_HOST: Server bind address (0.0.0.0 for all interfaces)
- HTTP_PORT: Server port number
- HTTP_PATH: API endpoint path
- CORS_ENABLED: Enable Cross-Origin Resource Sharing
- CORS_ORIGINS: Allowed CORS origins
- SSL_ENABLED: Enable HTTPS (requires certificates)#### HTTPS Transport Configuration (Secure)
Secure HTTP transport with SSL/TLS encryption:
`json
{
"mcpServers": {
"amazon-seller-https": {
"transport": {
"type": "http",
"host": "your-domain.com",
"port": 443,
"path": "/mcp",
"secure": true,
"headers": {
"Authorization": "Bearer your-secure-token",
"Content-Type": "application/json"
},
"tls": {
"rejectUnauthorized": true,
"ca": "/path/to/ca-cert.pem",
"cert": "/path/to/client-cert.pem",
"key": "/path/to/client-key.pem"
}
},
"env": {
"HTTPS_SERVER_MODE": "true",
"SSL_ENABLED": "true",
"SSL_CERT_PATH": "/path/to/server-cert.pem",
"SSL_KEY_PATH": "/path/to/server-key.pem",
"SSL_CA_PATH": "/path/to/ca-cert.pem",
"TLS_VERSION": "TLSv1.3",
"CIPHER_SUITES": "ECDHE-RSA-AES256-GCM-SHA384",
"VERIFY_CLIENT_CERT": "true"
}
}
}
}
`HTTPS Transport Benefits:
- โ
End-to-end encryption
- โ
Certificate-based authentication
- โ
Enterprise security compliance
- โ
Protection against MITM attacks
- โ
Audit trail capabilities
#### WebSocket Transport Configuration
Real-time bidirectional communication using WebSockets:
`json
{
"mcpServers": {
"amazon-seller-websocket": {
"transport": {
"type": "websocket",
"url": "ws://localhost:8080/mcp",
"protocols": ["mcp-v1"],
"headers": {
"Authorization": "Bearer your-websocket-token"
},
"options": {
"pingInterval": 30000,
"pongTimeout": 5000,
"reconnectInterval": 5000,
"maxReconnectAttempts": 10
}
},
"env": {
"WEBSOCKET_SERVER_MODE": "true",
"WS_HOST": "0.0.0.0",
"WS_PORT": "8080",
"WS_PATH": "/mcp",
"WS_PING_INTERVAL": "30000",
"WS_PONG_TIMEOUT": "5000",
"WS_MAX_PAYLOAD": "1048576",
"WS_COMPRESSION": "true"
}
}
}
}
`WebSocket Transport Benefits:
- โ
Real-time bidirectional communication
- โ
Lower latency than HTTP polling
- โ
Efficient for frequent updates
- โ
Built-in connection management
- โ
Support for streaming data
#### Environment-Specific Transport Configurations
Development Environment (stdio with debugging):
`json
{
"mcpServers": {
"amazon-seller-dev": {
"command": "npx",
"args": ["amazon-seller-mcp", "--dev-mode"],
"transport": {
"type": "stdio"
},
"env": {
"NODE_ENV": "development",
"TRANSPORT_MODE": "stdio",
"DEBUG_TRANSPORT": "true",
"LOG_TRANSPORT_EVENTS": "true",
"STDIO_BUFFER_SIZE": "16384",
"DEVELOPMENT_MODE": "true"
}
}
}
}
`Staging Environment (HTTP with monitoring):
`json
{
"mcpServers": {
"amazon-seller-staging": {
"transport": {
"type": "http",
"host": "staging-api.yourcompany.com",
"port": 8080,
"path": "/mcp/v1",
"headers": {
"Authorization": "Bearer staging-token",
"X-Environment": "staging"
}
},
"env": {
"NODE_ENV": "staging",
"HTTP_SERVER_MODE": "true",
"MONITORING_ENABLED": "true",
"METRICS_ENDPOINT": "/metrics",
"HEALTH_CHECK_ENDPOINT": "/health",
"REQUEST_LOGGING": "true"
}
}
}
}
`Production Environment (HTTPS with high availability):
`json
{
"mcpServers": {
"amazon-seller-prod": {
"transport": {
"type": "http",
"host": "api.yourcompany.com",
"port": 443,
"path": "/mcp/v1",
"secure": true,
"headers": {
"Authorization": "Bearer production-token",
"X-Environment": "production"
},
"tls": {
"rejectUnauthorized": true
}
},
"env": {
"NODE_ENV": "production",
"HTTPS_SERVER_MODE": "true",
"SSL_ENABLED": "true",
"LOAD_BALANCER_ENABLED": "true",
"CIRCUIT_BREAKER_ENABLED": "true",
"RATE_LIMITING_STRICT": "true",
"AUDIT_LOGGING": "true"
}
}
}
}
`#### Load Balanced Transport Configuration
For high-availability deployments with multiple server instances:
`json
{
"mcpServers": {
"amazon-seller-ha": {
"transport": {
"type": "http",
"loadBalancer": {
"strategy": "round-robin",
"healthCheck": {
"enabled": true,
"interval": 30000,
"timeout": 5000,
"path": "/health"
},
"servers": [
{
"host": "mcp-server-1.yourcompany.com",
"port": 8080,
"weight": 1
},
{
"host": "mcp-server-2.yourcompany.com",
"port": 8080,
"weight": 1
},
{
"host": "mcp-server-3.yourcompany.com",
"port": 8080,
"weight": 2
}
]
}
},
"env": {
"LOAD_BALANCER_MODE": "true",
"FAILOVER_ENABLED": "true",
"STICKY_SESSIONS": "false",
"CONNECTION_POOLING": "true",
"POOL_SIZE": "20"
}
}
}
}
`#### Proxy and Firewall Configuration
For environments with corporate proxies and firewalls:
`json
{
"mcpServers": {
"amazon-seller-proxy": {
"transport": {
"type": "http",
"host": "internal-mcp-server.corp.com",
"port": 8080,
"proxy": {
"host": "corporate-proxy.corp.com",
"port": 3128,
"auth": {
"username": "proxy-user",
"password": "proxy-password"
}
}
},
"env": {
"HTTP_PROXY": "http://corporate-proxy.corp.com:3128",
"HTTPS_PROXY": "http://corporate-proxy.corp.com:3128",
"NO_PROXY": "localhost,127.0.0.1,.corp.com",
"PROXY_AUTH_ENABLED": "true",
"FIREWALL_FRIENDLY": "true"
}
}
}
}
`#### Transport Performance Optimization
High-Throughput Configuration:
`json
{
"mcpServers": {
"amazon-seller-performance": {
"transport": {
"type": "http",
"host": "localhost",
"port": 8080,
"keepAlive": true,
"maxSockets": 50,
"timeout": 60000
},
"env": {
"TRANSPORT_OPTIMIZATION": "high-throughput",
"CONNECTION_POOL_SIZE": "50",
"KEEP_ALIVE_TIMEOUT": "60000",
"TCP_NO_DELAY": "true",
"SOCKET_REUSE": "true",
"COMPRESSION_ENABLED": "true"
}
}
}
}
`Low-Latency Configuration:
`json
{
"mcpServers": {
"amazon-seller-lowlatency": {
"transport": {
"type": "websocket",
"url": "ws://localhost:8080/mcp",
"options": {
"pingInterval": 10000,
"pongTimeout": 2000,
"maxPayload": 65536
}
},
"env": {
"TRANSPORT_OPTIMIZATION": "low-latency",
"WS_PING_INTERVAL": "10000",
"WS_PONG_TIMEOUT": "2000",
"BUFFER_SIZE": "65536",
"NAGLE_DISABLED": "true"
}
}
}
}
`#### Transport Security Best Practices
โ
Security Recommendations:
- Always use HTTPS in production environments
- Implement proper authentication tokens
- Enable certificate validation
- Use strong cipher suites
- Implement rate limiting
- Enable audit logging
- Rotate authentication tokens regularly
โ
Performance Recommendations:
- Use connection pooling for HTTP transport
- Enable compression for large payloads
- Implement proper timeout values
- Use keep-alive connections
- Monitor connection health
- Implement circuit breakers for resilience
โ
Monitoring Recommendations:
- Log all transport events
- Monitor connection metrics
- Set up health checks
- Track response times
- Monitor error rates
- Implement alerting for failures
---
๐ ๏ธ Available Tools & Resources
Comprehensive MCP tools and resources for Amazon seller operations.
$3
| Tool Category | Available Tools | Description |
|---------------|-----------------|-------------|
| Catalog |
search_products, get_product_details, get_categories | Product catalog operations |
| Listings | create_listing, update_listing, delete_listing, get_listings | Product listing management |
| Inventory | get_inventory, update_inventory, get_inventory_summary | Inventory tracking and updates |
| Orders | get_orders, get_order_details, update_order_status | Order processing and management |
| Reports | request_report, get_report_status, download_report | Analytics and reporting |
| AI Tools | generate-product-description, optimize-listing | AI-powered prompt generation for external AI assistants |$3
| Resource Type | URI Pattern | Description |
|---------------|-------------|-------------|
| Products |
amazon://products/{asin} | Product information and details |
| Listings | amazon://listings/{seller-sku} | Seller listing data |
| Orders | amazon://orders/{order-id} | Order information |
| Reports | amazon://reports/{report-id} | Generated reports |
| Inventory | amazon://inventory/{sku} | Inventory levels and status |---
๐ก Usage Examples
Practical examples for common Amazon seller operations.
$3
`typescript
// Create a new product listing
const listing = await mcpClient.call('create_listing', {
sku: 'MY-PRODUCT-001',
productType: 'PRODUCT',
attributes: {
title: 'Premium Wireless Headphones',
description: 'High-quality wireless headphones with noise cancellation',
price: 99.99,
quantity: 100
}
});
`$3
`typescript
// Generate optimized product description prompt
const descriptionPrompt = await mcpClient.call('generate-product-description', {
productTitle: 'Wireless Bluetooth Headphones',
keyFeatures: ['Noise Cancellation', '30-hour Battery', 'Premium Sound'],
targetAudience: 'Music enthusiasts and professionals'
});
`$3
`typescript
// Get current inventory levels
const inventory = await mcpClient.call('get_inventory', {
skus: ['SKU-001', 'SKU-002', 'SKU-003'],
marketplace: 'ATVPDKIKX0DER'
});
`---
๐ Authentication & Security
Secure setup and credential management for Amazon SP-API integration.
$3
1. Create Developer Account - Register at Amazon Developer Console
2. Create Application - Set up your SP-API application
3. Generate Credentials - Obtain Client ID, Client Secret, and Refresh Token
4. Configure Permissions - Set required API permissions
$3
- โ
Use environment variables for credentials
- โ
Implement credential rotation
- โ
Enable audit logging
- โ
Use least-privilege access
- โ Never commit credentials to version control
- โ Don't share credentials across environments
$3
`bash
Development
export AMAZON_CLIENT_ID="amzn1.application-oa2-client.dev"
export AMAZON_CLIENT_SECRET="dev_secret"
export AMAZON_REFRESH_TOKEN="dev_refresh_token"Production
export AMAZON_CLIENT_ID="amzn1.application-oa2-client.prod"
export AMAZON_CLIENT_SECRET="prod_secret"
export AMAZON_REFRESH_TOKEN="prod_refresh_token"
`---
๐ง Troubleshooting
Common issues and solutions for smooth operation.
$3
`bash
Check system requirements
amazon-seller-mcp --system-checkValidate credentials
amazon-seller-mcp --auth-testTest API connectivity
amazon-seller-mcp --connection-test
`$3
| Issue | Symptoms | Solution |
|-------|----------|----------|
| Auth Failure | 401/403 errors | Verify credentials and permissions |
| Rate Limiting | 429 errors | Implement exponential backoff |
| Network Issues | Timeout errors | Check firewall and proxy settings |
| Invalid SKU | 400 errors | Validate SKU format and existence |
$3
`bash
Enable debug mode
export LOG_LEVEL=debug
amazon-seller-mcpView detailed logs
tail -f ~/.amazon-seller-mcp/logs/debug.log
`---
๐ค Contributing
We welcome contributions from the community! Here's how to get started:
$3
`bash
Clone the repository
git clone https://github.com/enginterzi/amazon-seller-mcp.git
cd amazon-seller-mcpInstall dependencies
npm installRun tests
npm testStart development server
npm run dev
`$3
- ๐ Follow TypeScript best practices
- โ
Write comprehensive tests
- ๐ Update documentation
- ๐ Submit detailed pull requests
$3
The Amazon Seller MCP Client follows a modular architecture designed for extensibility and maintainability:
#### Core Components
`
src/
โโโ server/ # MCP Server Implementation
โ โโโ server.ts # Main MCP server with transport handling
โ โโโ tools.ts # Tool registration and management
โ โโโ resources.ts # Resource registration and management
โ โโโ notifications.ts # Real-time notification system
โโโ api/ # Amazon SP-API Client Layer
โ โโโ base-client.ts # Base HTTP client with auth
โ โโโ catalog-client.ts # Product catalog operations
โ โโโ listings-client.ts # Listing management
โ โโโ inventory-client.ts # Inventory operations
โ โโโ orders-client.ts # Order management
โโโ tools/ # MCP Tool Implementations
โ โโโ catalog-tools.ts # Product search and lookup
โ โโโ listings-tools.ts # Listing CRUD operations
โ โโโ inventory-tools.ts # Inventory management
โ โโโ orders-tools.ts # Order processing
โ โโโ ai-tools.ts # AI-assisted operations
โโโ resources/ # MCP Resource Providers
โ โโโ catalog/ # Product and category resources
โ โโโ listings/ # Listing data resources
โ โโโ inventory/ # Inventory status resources
โ โโโ orders/ # Order data resources
โโโ auth/ # Authentication Layer
โ โโโ amazon-auth.ts # OAuth token management
โ โโโ credential-manager.ts # Credential storage
โโโ utils/ # Shared Utilities
โโโ cache-manager.ts # Response caching
โโโ connection-pool.ts # HTTP connection pooling
`#### Data Flow Architecture
`mermaid
graph TB
A[AI Agent/Claude] --> B[MCP Protocol]
B --> C[MCP Server]
C --> D[Tool Registry]
C --> E[Resource Registry]
D --> F[Amazon SP-API Client]
E --> F
F --> G[Authentication Layer]
F --> H[Cache Manager]
F --> I[Connection Pool]
G --> J[Amazon SP-API]
H --> K[Local Cache]
I --> J
`#### Extension Points for New Features
1. Adding New API Endpoints
- Create new client in
src/api/ extending BaseClient
- Implement authentication and error handling
- Add rate limiting and caching as needed2. Creating New MCP Tools
- Add tool implementation in
src/tools/
- Register tool in src/server/tools.ts`**3. Adding New Resources