amazon-personal-shopping-mcp 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +159 -0
  3. package/dist/index.js +2671 -0
  4. package/dist/index.js.map +1 -0
  5. package/package.json +64 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Phil Patterson
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,159 @@
1
+ # amazon-personal-shopping-mcp
2
+
3
+ An MCP server that enables AI assistants to provide a full Amazon shopping experience through natural language. Search products, view details and reviews, manage your cart, view order history, and make purchases.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npx amazon-personal-shopping-mcp
9
+ ```
10
+
11
+ Requires Node.js 20 or later.
12
+
13
+ On first run, Playwright will automatically download the Chromium browser (~200MB). This only happens once.
14
+
15
+ ## Claude Desktop Configuration
16
+
17
+ Add this to your Claude Desktop configuration file:
18
+
19
+ **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
20
+
21
+ **Linux**: `~/.config/Claude/claude_desktop_config.json`
22
+
23
+ ```json
24
+ {
25
+ "mcpServers": {
26
+ "amazon-shopping": {
27
+ "command": "npx",
28
+ "args": ["-y", "amazon-personal-shopping-mcp"]
29
+ }
30
+ }
31
+ }
32
+ ```
33
+
34
+ After saving, completely quit and restart Claude Desktop.
35
+
36
+ ## Features
37
+
38
+ ### Authentication
39
+
40
+ | Tool | Description |
41
+ | ----------------------- | ----------------------------------------------------------------------------------------------------------- |
42
+ | `amazon-login` | Log in to Amazon. Opens a browser window for credentials and 2FA. Call this first before using other tools. |
43
+ | `amazon-session-status` | Check if you are currently logged in to Amazon. |
44
+
45
+ ### Search & Browse
46
+
47
+ | Tool | Description |
48
+ | --------------------- | ---------------------------------------------------------------------------------------------------------- |
49
+ | `search-products` | Search for products on Amazon. Returns ASIN, title, price, rating, brand, and Prime eligibility. |
50
+ | `get-product-details` | Get detailed product information by ASIN including description, features, price, availability, and images. |
51
+ | `get-reviews` | Get customer reviews for a product. Supports sorting by relevance/recency and filtering by star rating. |
52
+
53
+ ### Cart Management
54
+
55
+ | Tool | Description |
56
+ | ------------------ | --------------------------------------------------------------------- |
57
+ | `add-to-cart` | Add a product to your cart by ASIN with specified quantity. |
58
+ | `view-cart` | View cart contents including items, quantities, prices, and subtotal. |
59
+ | `remove-from-cart` | Remove a specific item from your cart. |
60
+ | `clear-cart` | Remove all items from your cart. |
61
+
62
+ ### Orders & Purchase
63
+
64
+ | Tool | Description |
65
+ | ------------------- | -------------------------------------------------------------------------- |
66
+ | `get-order-history` | View past orders with date filtering and pagination. |
67
+ | `get-order-details` | View detailed information about a specific order. |
68
+ | `perform-purchase` | Complete checkout and place an order. Requires explicit user confirmation. |
69
+
70
+ ## Usage Examples
71
+
72
+ **Search for a product:**
73
+
74
+ > "Search for wireless earbuds under $50 with good reviews"
75
+
76
+ **Get product details:**
77
+
78
+ > "Show me the details for this product" (after search)
79
+
80
+ **Add to cart:**
81
+
82
+ > "Add 2 of these to my cart"
83
+
84
+ **Check out:**
85
+
86
+ > "Show me my cart and help me check out"
87
+
88
+ **View orders:**
89
+
90
+ > "Show me my recent Amazon orders"
91
+
92
+ ## Environment Variables
93
+
94
+ | Variable | Description | Default |
95
+ | ---------------------- | ------------------------------- | ---------------- |
96
+ | `AMAZON_MCP_DEBUG` | Enable debug logging to stderr | `false` |
97
+ | `AMAZON_MCP_DATA_DIR` | Override data storage directory | Platform default |
98
+ | `AMAZON_MCP_CACHE_TTL` | Cache TTL in seconds | `600` (10 min) |
99
+ | `AMAZON_MCP_HEADLESS` | Run browser in headless mode | `true` |
100
+
101
+ Data is stored in:
102
+
103
+ - **macOS**: `~/Library/Application Support/amazon-personal-shopping-mcp/`
104
+ - **Linux**: `~/.local/share/amazon-personal-shopping-mcp/`
105
+
106
+ ## Troubleshooting
107
+
108
+ ### Browser installation fails
109
+
110
+ If Playwright browser installation fails, install manually:
111
+
112
+ ```bash
113
+ npx playwright install chromium
114
+ ```
115
+
116
+ ### Server doesn't start
117
+
118
+ Enable debug logging to see detailed error messages:
119
+
120
+ ```bash
121
+ AMAZON_MCP_DEBUG=true npx amazon-personal-shopping-mcp
122
+ ```
123
+
124
+ ### Authentication issues
125
+
126
+ Clear your saved session data and log in again:
127
+
128
+ **macOS**:
129
+
130
+ ```bash
131
+ rm -rf ~/Library/Application\ Support/amazon-personal-shopping-mcp/
132
+ ```
133
+
134
+ **Linux**:
135
+
136
+ ```bash
137
+ rm -rf ~/.local/share/amazon-personal-shopping-mcp/
138
+ ```
139
+
140
+ ### CAPTCHA challenges
141
+
142
+ If Amazon presents a CAPTCHA, the server will open a visible browser window. Complete the CAPTCHA manually and the operation will continue automatically.
143
+
144
+ ### Claude Desktop not connecting
145
+
146
+ 1. Verify the config file path is correct for your platform
147
+ 2. Ensure the JSON is valid (no trailing commas)
148
+ 3. Completely quit and restart Claude Desktop (not just close the window)
149
+ 4. Check Claude Desktop logs for connection errors
150
+
151
+ ## Platform Support
152
+
153
+ - macOS: Fully supported
154
+ - Linux: Fully supported
155
+ - Windows: Not currently supported
156
+
157
+ ## License
158
+
159
+ MIT