|
| 1 | +# Data Kiosk MCP Server |
| 2 | + |
| 3 | +A Model Context Protocol (MCP) server that enables AI assistants like Claude Desktop to interact with Amazon's Data Kiosk API for analyzing seller and vendor data. |
| 4 | + |
| 5 | +**This MCP server example runs locally in your test environment and provides a foundation for development and experimentation. Developers utilizing this sample solution are responsible for its implementation, usage patterns, and ensuring compliance with Amazon's Acceptable Use Policy (AUP) and Data Protection Policy (DPP).** |
| 6 | + |
| 7 | +https://github.com/user-attachments/assets/e90896e6-bec2-4a5b-ad42-81052feada1d |
| 8 | + |
| 9 | + |
| 10 | +## Overview |
| 11 | + |
| 12 | +This MCP server provides a bridge between AI assistants and Amazon's Data Kiosk API, allowing for powerful analytics capabilities through natural language conversations. It enables users to: |
| 13 | + |
| 14 | +- Query Sales and Traffic data for Amazon sellers |
| 15 | +- Analyze Economics and Profitability metrics |
| 16 | +- Examine Vendor Analytics data |
| 17 | +- Build and execute GraphQL queries |
| 18 | +- Monitor query processing |
| 19 | +- Download and analyze query results |
| 20 | + |
| 21 | +## Architecture |
| 22 | + |
| 23 | +The project is structured as a monorepo with three packages: |
| 24 | + |
| 25 | +1. **common**: Shared utilities and base functionality |
| 26 | + - Authentication with Amazon Selling Partner API |
| 27 | + - Base API interaction |
| 28 | + - GraphQL query helpers |
| 29 | + - Utility functions |
| 30 | + |
| 31 | +2. **seller-server**: MCP server for Amazon Seller Analytics |
| 32 | + - Sales and Traffic analytics tools |
| 33 | + - Economics data tools |
| 34 | + - Example query builders |
| 35 | + |
| 36 | +3. **vendor-server**: MCP server for Amazon Vendor Analytics |
| 37 | + - Sourcing view analytics |
| 38 | + - Manufacturing view analytics |
| 39 | + - Example query builders |
| 40 | + |
| 41 | +## Prerequisites |
| 42 | + |
| 43 | +- Node.js v16 or higher |
| 44 | +- An Amazon Seller Central or Vendor Central account with Data Kiosk access |
| 45 | +- Amazon Selling Partner API credentials: |
| 46 | + - Client ID |
| 47 | + - Client Secret |
| 48 | + - Refresh Token |
| 49 | + |
| 50 | +## Installation |
| 51 | + |
| 52 | +1. Clone the repository: |
| 53 | +```bash |
| 54 | +git clone https://github.com/amzn/selling-partner-api-samples.git |
| 55 | +cd use-cases/amazon-data-kiosk-mcp-server |
| 56 | +``` |
| 57 | + |
| 58 | +2. Install dependencies: |
| 59 | +```bash |
| 60 | +npm install |
| 61 | +``` |
| 62 | + |
| 63 | +3. Build all packages: |
| 64 | +```bash |
| 65 | +npm run build |
| 66 | +``` |
| 67 | + |
| 68 | +## Configuration |
| 69 | + |
| 70 | +### Environment Variables |
| 71 | + |
| 72 | +Set the following environment variables: |
| 73 | + |
| 74 | +``` |
| 75 | +DATA_KIOSK_CLIENT_ID=your_client_id |
| 76 | +DATA_KIOSK_CLIENT_SECRET=your_client_secret |
| 77 | +DATA_KIOSK_REFRESH_TOKEN=your_refresh_token |
| 78 | +DATA_KIOSK_BASE_URL=https://sellingpartnerapi-na.amazon.com |
| 79 | +DATA_KIOSK_OAUTH_URL=https://api.amazon.com/auth/o2/token |
| 80 | +DATA_KIOSK_API_VERSION=2023-11-15 |
| 81 | +``` |
| 82 | + |
| 83 | +### MCP Client Configuration (Using Claude Desktop as an Example) |
| 84 | + |
| 85 | +Add the server to your Claude Desktop configuration file located at: |
| 86 | +- macOS/Linux: `~/Library/Application Support/Claude/claude_desktop_config.json` |
| 87 | +- Windows: `%AppData%\Claude\claude_desktop_config.json` |
| 88 | + |
| 89 | +**Note:** While you can add both the seller and vendor servers to your configuration, it's recommended to add only one at a time to avoid confusion for the AI model. Choose the server that matches your account type (seller or vendor). |
| 90 | + |
| 91 | +```json |
| 92 | +{ |
| 93 | + "mcpServers": { |
| 94 | + "amazon-seller-analytics": { |
| 95 | + "command": "node", |
| 96 | + "args": [ |
| 97 | + "/absolute/path/to/amazon-data-kiosk-mcp-server/packages/seller-server/build/index.js" |
| 98 | + ], |
| 99 | + "env": { |
| 100 | + "DATA_KIOSK_CLIENT_ID": "your_client_id", |
| 101 | + "DATA_KIOSK_CLIENT_SECRET": "your_client_secret", |
| 102 | + "DATA_KIOSK_REFRESH_TOKEN": "your_refresh_token", |
| 103 | + "DATA_KIOSK_BASE_URL": "https://sellingpartnerapi-na.amazon.com", |
| 104 | + "DATA_KIOSK_OAUTH_URL": "https://api.amazon.com/auth/o2/token", |
| 105 | + "DATA_KIOSK_API_VERSION": "2023-11-15" |
| 106 | + } |
| 107 | + } |
| 108 | + } |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +## Usage |
| 113 | + |
| 114 | +1. Start Claude Desktop |
| 115 | +2. Verify the MCP server is connected by checking for the tools icon |
| 116 | +3. Ask Claude about your Amazon seller or vendor data |
| 117 | + |
| 118 | +### Example Prompts |
| 119 | + |
| 120 | +For Sellers: |
| 121 | +- "What were my sales trends last month?" |
| 122 | +- "Show me my top-selling products by ASIN" |
| 123 | +- "What's my conversion rate and buy box percentage?" |
| 124 | +- "Analyze my profitability after all Amazon fees" |
| 125 | +- "What's the impact of the recent FBA fee changes on my products?" |
| 126 | + |
| 127 | +For Vendors: |
| 128 | +- "What's my inventory health across product categories?" |
| 129 | +- "Show me my purchase order fill rate trends" |
| 130 | +- "What's my forecast accuracy for the last quarter?" |
| 131 | +- "Analyze my shipped revenue by brand" |
| 132 | + |
| 133 | +## Available Tools |
| 134 | + |
| 135 | +### General Tools |
| 136 | +- `list-queries`: List all Data Kiosk queries with optional filtering |
| 137 | +- `create-query`: Create a new GraphQL query for retrieving business analytics data |
| 138 | +- `check-query-status`: Check the status of a specific query |
| 139 | +- `cancel-query`: Cancel a running query |
| 140 | +- `get-document-details`: Get details of a document, including the download URL |
| 141 | +- `download-document`: Download the content of a document using its URL |
| 142 | +- `get-api-help`: Get help information about the Amazon Data Kiosk API |
| 143 | + |
| 144 | +### Seller Analytics Tools |
| 145 | +- `explore-sales-and-traffic-schema`: Explore the Sales and Traffic GraphQL schema structure |
| 146 | +- `build-sales-and-traffic-query`: Build a GraphQL query for sales and traffic based on parameters |
| 147 | +- `get-sales-and-traffic-example`: Get example GraphQL queries for sales and traffic data |
| 148 | +- `explore-economics-schema`: Explore the Seller Economics GraphQL schema structure |
| 149 | +- `build-economics-query`: Build a GraphQL query for seller economics data |
| 150 | +- `build-economics-preview-query`: Build a GraphQL query to preview future seller economics based on fee changes |
| 151 | +- `get-economics-example`: Get example GraphQL queries for seller economics data |
| 152 | + |
| 153 | +### Vendor Analytics Tools |
| 154 | +- `explore-vendor-analytics-schema`: Explore the Vendor Analytics GraphQL schema structure |
| 155 | +- `build-vendor-analytics-query`: Build a GraphQL query for vendor analytics based on parameters |
| 156 | +- `get-vendor-analytics-example`: Get example GraphQL queries for vendor analytics |
| 157 | + |
| 158 | +## Technical Details |
| 159 | + |
| 160 | +### Data Kiosk API |
| 161 | + |
| 162 | +The server interacts with Amazon's Data Kiosk API, which provides: |
| 163 | +- GraphQL-based query interface |
| 164 | +- JSONL format results |
| 165 | +- Support for multiple data domains (Sales, Economics, Vendor Analytics) |
| 166 | +- Asynchronous query processing |
| 167 | + |
| 168 | +### MCP Integration |
| 169 | + |
| 170 | +This project uses the Model Context Protocol to: |
| 171 | +- Expose tools to AI assistants like Claude |
| 172 | +- Process natural language requests into structured API calls |
| 173 | +- Format API responses for conversational use |
| 174 | +- Guide users through complex analytics workflows |
| 175 | + |
| 176 | +## Troubleshooting |
| 177 | + |
| 178 | +If the MCP server isn't connecting to Claude Desktop: |
| 179 | +1. Check the Claude logs at `~/Library/Logs/Claude/mcp*.log` |
| 180 | +2. Verify the path in `claude_desktop_config.json` is correct and absolute |
| 181 | +3. Make sure the server is built (`npm run build`) |
| 182 | +4. Ensure all environment variables are set correctly |
| 183 | +5. Restart Claude Desktop |
| 184 | + |
| 185 | +## Security Considerations |
| 186 | + |
| 187 | +- This server requires access to sensitive Amazon API credentials |
| 188 | +- Never share your client secret or refresh token |
| 189 | +- Consider using a dedicated IAM user with minimal permissions |
| 190 | +- Review Amazon's security best practices for the Selling Partner API |
| 191 | + |
| 192 | +## License |
| 193 | + |
| 194 | +MIT |
| 195 | + |
| 196 | +## Contributing |
| 197 | + |
| 198 | +Contributions are welcome! Please feel free to submit a Pull Request. |
| 199 | + |
| 200 | +## Acknowledgements |
| 201 | + |
| 202 | +- This project utilizes the Model Context Protocol developed by Anthropic |
| 203 | +- Built for the Amazon Selling Partner API and Data Kiosk API |
0 commit comments