hasdata-amazon-mcp 1.0.0__tar.gz
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.
- hasdata_amazon_mcp-1.0.0/.github/ISSUE_TEMPLATE/inaccuracy.md +21 -0
- hasdata_amazon_mcp-1.0.0/.github/workflows/contract.yml +31 -0
- hasdata_amazon_mcp-1.0.0/.github/workflows/publish.yml +75 -0
- hasdata_amazon_mcp-1.0.0/.gitignore +11 -0
- hasdata_amazon_mcp-1.0.0/LICENSE +21 -0
- hasdata_amazon_mcp-1.0.0/PKG-INFO +420 -0
- hasdata_amazon_mcp-1.0.0/README.md +406 -0
- hasdata_amazon_mcp-1.0.0/glama.json +7 -0
- hasdata_amazon_mcp-1.0.0/hasdata_amazon_mcp/__init__.py +28 -0
- hasdata_amazon_mcp-1.0.0/index.mjs +24 -0
- hasdata_amazon_mcp-1.0.0/package.json +41 -0
- hasdata_amazon_mcp-1.0.0/pyproject.toml +24 -0
- hasdata_amazon_mcp-1.0.0/server.json +61 -0
- hasdata_amazon_mcp-1.0.0/test/tools.test.mjs +176 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Something in the README is wrong
|
|
3
|
+
about: A tool table, a response sample or a documented behaviour does not match reality
|
|
4
|
+
labels: documentation
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
**Where in the README**
|
|
8
|
+
|
|
9
|
+
Section or heading.
|
|
10
|
+
|
|
11
|
+
**What it says**
|
|
12
|
+
|
|
13
|
+
Quote the line.
|
|
14
|
+
|
|
15
|
+
**The call you made**
|
|
16
|
+
|
|
17
|
+
Tool name and arguments, or the equivalent REST URL with your key removed.
|
|
18
|
+
|
|
19
|
+
**What came back**
|
|
20
|
+
|
|
21
|
+
Trimmed response, with anything private removed.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# The tool contract is checked on a schedule as well as on push, because the upstream tool list
|
|
2
|
+
# can change without a single commit in this repository.
|
|
3
|
+
name: tool contract
|
|
4
|
+
|
|
5
|
+
on:
|
|
6
|
+
push:
|
|
7
|
+
branches: [main]
|
|
8
|
+
pull_request:
|
|
9
|
+
schedule:
|
|
10
|
+
- cron: '0 6 * * 1'
|
|
11
|
+
workflow_dispatch:
|
|
12
|
+
|
|
13
|
+
permissions:
|
|
14
|
+
contents: read
|
|
15
|
+
|
|
16
|
+
jobs:
|
|
17
|
+
contract:
|
|
18
|
+
runs-on: ubuntu-latest
|
|
19
|
+
timeout-minutes: 5
|
|
20
|
+
steps:
|
|
21
|
+
- uses: actions/checkout@v4
|
|
22
|
+
- uses: actions/setup-node@v4
|
|
23
|
+
with:
|
|
24
|
+
node-version: '22'
|
|
25
|
+
# Forks cannot read repository secrets. The suite skips its live checks when the key is
|
|
26
|
+
# absent, so a pull request from a fork stays green instead of failing for a reason the
|
|
27
|
+
# contributor cannot fix.
|
|
28
|
+
- name: Assert the tool list still matches the README
|
|
29
|
+
env:
|
|
30
|
+
HASDATA_API_KEY: ${{ secrets.HASDATA_API_KEY }}
|
|
31
|
+
run: npm test
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Publishes the npm and PyPI wrapper packages on a version tag, using OIDC
|
|
2
|
+
# trusted publishing. No NPM_TOKEN or PYPI_TOKEN is stored anywhere: GitHub
|
|
3
|
+
# mints a short-lived OIDC token per run, and npmjs.org / pypi.org accept it
|
|
4
|
+
# because this repo + workflow are configured as trusted publishers.
|
|
5
|
+
#
|
|
6
|
+
# One-time setup, done once per package on the registries (not in this repo):
|
|
7
|
+
# npmjs.org -> package settings -> Trusted Publisher -> GitHub Actions,
|
|
8
|
+
# repo HasData/amazon-mcp, workflow publish.yml
|
|
9
|
+
# pypi.org -> the hasdata org -> Publishing -> add a trusted publisher
|
|
10
|
+
# (pending publisher works before the first release),
|
|
11
|
+
# repo HasData/amazon-mcp, workflow publish.yml
|
|
12
|
+
#
|
|
13
|
+
# The MCP registry entry (com.hasdata/amazon) is NOT published here. It uses
|
|
14
|
+
# domain auth, which would need the namespace-wide Ed25519 key as a secret in
|
|
15
|
+
# every repo. That key stays off CI; the registry entry is published by hand
|
|
16
|
+
# when server.json changes, after the package versions below are live.
|
|
17
|
+
#
|
|
18
|
+
# Release: bump nothing by hand. Tag the commit `vX.Y.Z` and push the tag; the
|
|
19
|
+
# tag is the single source of the version and is written into both manifests.
|
|
20
|
+
|
|
21
|
+
name: publish
|
|
22
|
+
|
|
23
|
+
on:
|
|
24
|
+
push:
|
|
25
|
+
tags: ['v*.*.*']
|
|
26
|
+
|
|
27
|
+
permissions:
|
|
28
|
+
contents: read
|
|
29
|
+
id-token: write
|
|
30
|
+
|
|
31
|
+
jobs:
|
|
32
|
+
npm:
|
|
33
|
+
runs-on: ubuntu-latest
|
|
34
|
+
steps:
|
|
35
|
+
- uses: actions/checkout@v4
|
|
36
|
+
# No registry-url here on purpose. With it, setup-node writes an .npmrc
|
|
37
|
+
# carrying _authToken=${NODE_AUTH_TOKEN}, which resolves to a placeholder
|
|
38
|
+
# when no token is passed. npm then authenticates with that garbage instead
|
|
39
|
+
# of falling back to OIDC, and a scoped package answers 404.
|
|
40
|
+
- uses: actions/setup-node@v4
|
|
41
|
+
with:
|
|
42
|
+
node-version: '24'
|
|
43
|
+
# OIDC trusted publishing landed in npm 11.5.1. Node 24 already ships a
|
|
44
|
+
# newer npm than that, but pinning the upgrade here keeps the job working
|
|
45
|
+
# if the runner image drifts back.
|
|
46
|
+
- name: Upgrade npm for OIDC trusted publishing
|
|
47
|
+
run: |
|
|
48
|
+
npm install -g npm@latest
|
|
49
|
+
npm -v
|
|
50
|
+
- name: Set version from the tag
|
|
51
|
+
run: npm version "${GITHUB_REF_NAME#v}" --no-git-tag-version --allow-same-version
|
|
52
|
+
- name: Publish to npm (OIDC, no token)
|
|
53
|
+
run: npm publish --access public
|
|
54
|
+
|
|
55
|
+
pypi:
|
|
56
|
+
runs-on: ubuntu-latest
|
|
57
|
+
steps:
|
|
58
|
+
- uses: actions/checkout@v4
|
|
59
|
+
- uses: actions/setup-python@v5
|
|
60
|
+
with:
|
|
61
|
+
python-version: '3.12'
|
|
62
|
+
- name: Set version from the tag
|
|
63
|
+
run: |
|
|
64
|
+
python - "${GITHUB_REF_NAME#v}" <<'PY'
|
|
65
|
+
import re, sys
|
|
66
|
+
v = sys.argv[1]
|
|
67
|
+
p = "pyproject.toml"
|
|
68
|
+
t = open(p, encoding="utf-8").read()
|
|
69
|
+
t = re.sub(r'(?m)^version = ".*"$', f'version = "{v}"', t, count=1)
|
|
70
|
+
open(p, "w", encoding="utf-8", newline="\n").write(t)
|
|
71
|
+
PY
|
|
72
|
+
- name: Build the wheel and sdist
|
|
73
|
+
run: pipx run build
|
|
74
|
+
- name: Publish to PyPI (OIDC, no token)
|
|
75
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HasData
|
|
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.
|
|
@@ -0,0 +1,420 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: hasdata-amazon-mcp
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: MCP server for Amazon through HasData's hosted API. 1,000 free credits every month.
|
|
5
|
+
Project-URL: Homepage, https://hasdata.com/apis/amazon-api
|
|
6
|
+
Project-URL: Repository, https://github.com/HasData/amazon-mcp
|
|
7
|
+
License: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Keywords: amazon,asin,ecommerce,hasdata,mcp,model-context-protocol,product-data
|
|
10
|
+
Requires-Python: >=3.10
|
|
11
|
+
Requires-Dist: mcp-proxy>=0.12.0
|
|
12
|
+
Requires-Dist: mcp<2,>=1.17
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
|
|
15
|
+
# Amazon MCP Server
|
|
16
|
+
|
|
17
|
+
<!-- mcp-name: com.hasdata/amazon -->
|
|
18
|
+
|
|
19
|
+
A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client four read-only Amazon tools. Run a keyword search, read one product by its ASIN, look up a seller, and page through what that seller stocks, all as structured JSON, with no Amazon developer account and nothing to host.
|
|
20
|
+
|
|
21
|
+
It reads public Amazon pages that a signed-out visitor can see, on any of the 23 regional domains.
|
|
22
|
+
|
|
23
|
+
**1,000 free credits every month, no card required**, which is 200 Amazon calls at the 5-credit rate.
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
https://mcp.hasdata.com/api/mcp?apis=amazon
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
[](https://glama.ai/mcp/servers/HasData/amazon-mcp)
|
|
30
|
+
[](https://github.com/HasData/amazon-mcp/actions/workflows/contract.yml)
|
|
31
|
+
[](https://mcp.hasdata.com/api/mcp?apis=amazon)
|
|
32
|
+
[](#tools)
|
|
33
|
+
[](https://www.npmjs.com/package/@hasdata/amazon-mcp)
|
|
34
|
+
[](https://pypi.org/project/hasdata-amazon-mcp/)
|
|
35
|
+
[](LICENSE)
|
|
36
|
+
|
|
37
|
+
## Contents
|
|
38
|
+
|
|
39
|
+
- [What you need](#what-you-need)
|
|
40
|
+
- [Quick start](#quick-start)
|
|
41
|
+
- [Example prompts](#example-prompts)
|
|
42
|
+
- [Tools](#tools)
|
|
43
|
+
- [Errors and failure paths](#errors-and-failure-paths)
|
|
44
|
+
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
|
|
45
|
+
- [Tool selection](#tool-selection)
|
|
46
|
+
- [How it compares](#how-it-compares)
|
|
47
|
+
- [FAQ](#faq)
|
|
48
|
+
- [HasData links](#hasdata-links)
|
|
49
|
+
- [Development](#development)
|
|
50
|
+
- [Contributing](#contributing)
|
|
51
|
+
- [License](#license)
|
|
52
|
+
|
|
53
|
+
## What you need
|
|
54
|
+
|
|
55
|
+
An MCP client and a HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp), free to create with no card, and the free tier covers about 200 calls a month at the 5-credit rate. This is a remote server, so the simplest path is a URL and an `x-api-key` header, with no container to run. A client that only speaks stdio reaches it through a thin launcher, published as `@hasdata/amazon-mcp` on npm and `hasdata-amazon-mcp` on PyPI, shown below.
|
|
56
|
+
|
|
57
|
+
## Quick start
|
|
58
|
+
|
|
59
|
+
The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.
|
|
60
|
+
|
|
61
|
+
| Field | Value |
|
|
62
|
+
| :--- | :--- |
|
|
63
|
+
| URL | `https://mcp.hasdata.com/api/mcp?apis=amazon` |
|
|
64
|
+
| Transport | HTTP, streamable |
|
|
65
|
+
| Auth header | `x-api-key: HASDATA_API_KEY` |
|
|
66
|
+
|
|
67
|
+
Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.
|
|
68
|
+
|
|
69
|
+
<details>
|
|
70
|
+
<summary><b>Claude Code</b></summary>
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
claude mcp add --transport http amazon "https://mcp.hasdata.com/api/mcp?apis=amazon" \
|
|
74
|
+
--header "x-api-key: HASDATA_API_KEY"
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
</details>
|
|
78
|
+
|
|
79
|
+
<details>
|
|
80
|
+
<summary><b>Claude Desktop</b></summary>
|
|
81
|
+
|
|
82
|
+
Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=amazon` and sign in.
|
|
83
|
+
|
|
84
|
+
For the config-file route, Claude Desktop loads only local (stdio) servers, so it reaches a remote server through a stdio launcher. The `@hasdata/amazon-mcp` package is that launcher, and it reads the key from the environment. Add this to `claude_desktop_config.json`:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"mcpServers": {
|
|
89
|
+
"amazon": {
|
|
90
|
+
"command": "npx",
|
|
91
|
+
"args": ["-y", "@hasdata/amazon-mcp"],
|
|
92
|
+
"env": { "HASDATA_API_KEY": "YOUR_KEY" }
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
For Python instead of Node, swap the launcher for the PyPI package, which `uvx` runs without a manual install:
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"mcpServers": {
|
|
103
|
+
"amazon": {
|
|
104
|
+
"command": "uvx",
|
|
105
|
+
"args": ["hasdata-amazon-mcp"],
|
|
106
|
+
"env": { "HASDATA_API_KEY": "YOUR_KEY" }
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
</details>
|
|
113
|
+
|
|
114
|
+
<details>
|
|
115
|
+
<summary><b>Cursor</b></summary>
|
|
116
|
+
|
|
117
|
+
`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"mcpServers": {
|
|
122
|
+
"amazon": {
|
|
123
|
+
"url": "https://mcp.hasdata.com/api/mcp?apis=amazon",
|
|
124
|
+
"headers": { "x-api-key": "HASDATA_API_KEY" }
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
</details>
|
|
131
|
+
|
|
132
|
+
<details>
|
|
133
|
+
<summary><b>Windsurf</b></summary>
|
|
134
|
+
|
|
135
|
+
`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"mcpServers": {
|
|
140
|
+
"amazon": {
|
|
141
|
+
"serverUrl": "https://mcp.hasdata.com/api/mcp?apis=amazon",
|
|
142
|
+
"headers": { "x-api-key": "HASDATA_API_KEY" }
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
</details>
|
|
149
|
+
|
|
150
|
+
<details>
|
|
151
|
+
<summary><b>VS Code</b></summary>
|
|
152
|
+
|
|
153
|
+
`.vscode/mcp.json` in the workspace:
|
|
154
|
+
|
|
155
|
+
```json
|
|
156
|
+
{
|
|
157
|
+
"servers": {
|
|
158
|
+
"amazon": {
|
|
159
|
+
"type": "http",
|
|
160
|
+
"url": "https://mcp.hasdata.com/api/mcp?apis=amazon",
|
|
161
|
+
"headers": { "x-api-key": "HASDATA_API_KEY" }
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
</details>
|
|
168
|
+
|
|
169
|
+
## Example prompts
|
|
170
|
+
|
|
171
|
+
Each of these lands on one tool, or on two in sequence when the second needs an identifier the first returns.
|
|
172
|
+
|
|
173
|
+
- Find laptop stands under $40 on Amazon and sort them by average customer review.
|
|
174
|
+
- What does ASIN B0DHJ7SBDR cost right now, and how many other sellers offer it?
|
|
175
|
+
- Compare the price of this ASIN on amazon.com and amazon.de.
|
|
176
|
+
- Who is the seller behind ASIN B0DHJ7SBDR, and what is their lifetime rating?
|
|
177
|
+
- Page through everything seller ATQQBVXK188KS stocks and pull out the discounted items.
|
|
178
|
+
- Search for wireless earbuds with delivery to 10001 and tell me which arrive fastest.
|
|
179
|
+
|
|
180
|
+
A prompt that names a product rather than an ASIN takes two calls, one search to resolve the ASIN and one product lookup to read it. A prompt that names a seller by brand rather than by seller ID takes the same shape, one product lookup to find the seller ID and one seller lookup to read the profile.
|
|
181
|
+
|
|
182
|
+
## Tools
|
|
183
|
+
|
|
184
|
+
Four tools, 5 credits per successful call. Every tool accepts `domain` to switch marketplace, one of 23 values, `www.amazon.com` through the European, Asian and other regional marketplaces, and `language` where the marketplace offers more than one.
|
|
185
|
+
|
|
186
|
+
### Get Amazon search results
|
|
187
|
+
|
|
188
|
+
[`hasdata_amazon_search_getSearchResults`](https://docs.hasdata.com/apis/amazon/search?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp)
|
|
189
|
+
|
|
190
|
+
A page of search results for a keyword.
|
|
191
|
+
|
|
192
|
+
| Parameter | Type | Required | Notes |
|
|
193
|
+
| :--- | :--- | :--- | :--- |
|
|
194
|
+
| `q` | string | yes | The search term |
|
|
195
|
+
| `domain` | string | | Marketplace, defaults to `www.amazon.com` |
|
|
196
|
+
| `page` | number | | Result page, starting at 1 |
|
|
197
|
+
| `sortBy` | string | | `featured`, `priceLowToHigh`, `priceHighToLow`, `avgCustomerReview`, `newestArrivals` or `bestSellers` |
|
|
198
|
+
| `deliveryZip` | string | | Postal code, which changes availability and delivery dates |
|
|
199
|
+
| `shippingLocation` | string | | Two-letter country code for the delivery address |
|
|
200
|
+
| `language` | string | | Marketplace language code |
|
|
201
|
+
|
|
202
|
+
Returns `productResults`, an `ads` array of sponsored placements, and `pagination` with `totalResults`, `currentPage`, `nextPageUrl` and `otherPageUrls`. Each result carries `position`, `asin`, `title`, `url`, `isSponsored`, a `price` object, `image`, `reviews` with `rating` and `totalReviews`, a `badges` object, `boughtInPastMonth` and `deliveryInfo`.
|
|
203
|
+
|
|
204
|
+
> A search result is deliberately thin. Brand, features, variants, images and the seller are not here, they come from the product tool below. Resolve the ASIN first, then read the product.
|
|
205
|
+
|
|
206
|
+
```json
|
|
207
|
+
{
|
|
208
|
+
"position": 1,
|
|
209
|
+
"asin": "B077B9W343",
|
|
210
|
+
"title": "Nulaxy Ergonomic Adjustable Laptop Stand for Desk, Dual Foldable Computer Riser...",
|
|
211
|
+
"isSponsored": false,
|
|
212
|
+
"price": { "symbol": "$", "currentPrice": 15.99, "beforePrice": 17.99 },
|
|
213
|
+
"image": "https://m.media-amazon.com/images/I/61jtA8kHq9L.jpg",
|
|
214
|
+
"reviews": { "totalReviews": 16800, "rating": 4.7 },
|
|
215
|
+
"badges": { "amazonChoice": true, "amazonPrime": false, "bestSeller": false },
|
|
216
|
+
"boughtInPastMonth": "10K+",
|
|
217
|
+
"deliveryInfo": { "freeDelivery": "Join Prime", "fastestDelivery": "Mon, Sep 14" },
|
|
218
|
+
"url": "https://www.amazon.com/dp/B077B9W343"
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### Get Amazon product details
|
|
223
|
+
|
|
224
|
+
[`hasdata_amazon_product_getProductDetails`](https://docs.hasdata.com/apis/amazon/product?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp)
|
|
225
|
+
|
|
226
|
+
One product in full, by its ASIN.
|
|
227
|
+
|
|
228
|
+
| Parameter | Type | Required | Notes |
|
|
229
|
+
| :--- | :--- | :--- | :--- |
|
|
230
|
+
| `asin` | string | yes | The Amazon Standard Identification Number |
|
|
231
|
+
| `domain` | string | | Marketplace, defaults to `www.amazon.com` |
|
|
232
|
+
| `otherSellers` | boolean | | Also collect competing offers. Costs 5 credits on top of the base, 10 instead of 5 |
|
|
233
|
+
| `deliveryZip` | string | | Postal code, which changes availability and delivery dates |
|
|
234
|
+
| `shippingLocation` | string | | Two-letter country code for the delivery address |
|
|
235
|
+
| `language` | string | | Marketplace language code |
|
|
236
|
+
|
|
237
|
+
Returns a `product` object with `asin`, `url`, `title`, `brand`, `isAvailable`, `condition`, a `price` object, `primaryFeatures` and a wider `features` map, `featureBullets`, `description`, `variants`, `breadcrumbs`, `whatIsInTheBox`, image and video collections, `specification`, `reviewsInfo`, the delivery estimates, and the current `seller` with `sellerUrl`.
|
|
238
|
+
|
|
239
|
+
The `price` object holds `currentPrice`, `beforePrice` when the item is discounted, `discount`, `priceFrom` and `otherOfferQuantity`. That last field is a count of competing offers, which the base call reports without fetching them. Ask for `otherSellers` only when the offers themselves are needed, because it doubles the price of the call.
|
|
240
|
+
|
|
241
|
+
```json
|
|
242
|
+
{
|
|
243
|
+
"asin": "B0DHJ7SBDR",
|
|
244
|
+
"title": "Apple iPhone 16 Pro Max, 1TB, Desert Titanium",
|
|
245
|
+
"brand": "Apple",
|
|
246
|
+
"condition": "Refurbished - Excellent",
|
|
247
|
+
"price": {
|
|
248
|
+
"symbol": "$",
|
|
249
|
+
"currentPrice": 974,
|
|
250
|
+
"beforePrice": 949.99,
|
|
251
|
+
"discount": "-11%",
|
|
252
|
+
"otherOfferQuantity": 11
|
|
253
|
+
},
|
|
254
|
+
"seller": "WirelessSource",
|
|
255
|
+
"deliveryIsoDate": "2026-09-11T00:00:00.000Z"
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
### Get Amazon seller details
|
|
260
|
+
|
|
261
|
+
[`hasdata_amazon_seller_getSellerDetails`](https://docs.hasdata.com/apis/amazon/seller?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp)
|
|
262
|
+
|
|
263
|
+
The public storefront profile of one seller.
|
|
264
|
+
|
|
265
|
+
| Parameter | Type | Required | Notes |
|
|
266
|
+
| :--- | :--- | :--- | :--- |
|
|
267
|
+
| `sellerId` | string | yes | The seller ID, which a product response returns in `sellerUrl` |
|
|
268
|
+
| `domain` | string | | Marketplace, defaults to `www.amazon.com` |
|
|
269
|
+
| `language` | string | | Marketplace language code |
|
|
270
|
+
|
|
271
|
+
Returns a `seller` object with `sellerId`, `url`, `storefrontUrl`, `name`, `businessName`, `businessAddress`, an `about` block, and four rating windows named `oneMonthRatings`, `threeMonthRatings`, `twelveMonthRating` and `lifetimeRating`. Each window carries `totalVotes`, `averageRating` and a per-star breakdown with both `votes` and `percent`.
|
|
272
|
+
|
|
273
|
+
The four windows are what make this tool worth a call. A lifetime average of 4.5 over 2,701 votes and a one-month average of 2 over 4 votes describe very different sellers, and only the pair shows a decline in progress.
|
|
274
|
+
|
|
275
|
+
```json
|
|
276
|
+
{
|
|
277
|
+
"sellerId": "ATQQBVXK188KS",
|
|
278
|
+
"name": "Expercom - Apple Premier Partner",
|
|
279
|
+
"businessName": "Expercom of Utah, Inc",
|
|
280
|
+
"lifetimeRating": { "totalVotes": 2701, "averageRating": 4.5 },
|
|
281
|
+
"oneMonthRatings": { "totalVotes": 4, "averageRating": 2 }
|
|
282
|
+
}
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
### Get Amazon seller products
|
|
286
|
+
|
|
287
|
+
[`hasdata_amazon_seller_products_getSellerProducts`](https://docs.hasdata.com/apis/amazon/seller-products?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp)
|
|
288
|
+
|
|
289
|
+
A page of what one seller stocks.
|
|
290
|
+
|
|
291
|
+
| Parameter | Type | Required | Notes |
|
|
292
|
+
| :--- | :--- | :--- | :--- |
|
|
293
|
+
| `sellerId` | string | yes | The seller ID |
|
|
294
|
+
| `domain` | string | | Marketplace, defaults to `www.amazon.com` |
|
|
295
|
+
| `page` | number | | Result page, starting at 1 |
|
|
296
|
+
| `language` | string | | Marketplace language code |
|
|
297
|
+
|
|
298
|
+
Returns `productResults` and `pagination`, shaped like the search tool's output. Each item carries `position`, `asin`, `title`, `url`, `price`, `image`, `reviews`, `badges`, `boughtInPastMonth`, `deliveryInfo` and `colorUrls`. Walk `pagination` to reach the rest of the catalogue rather than guessing page numbers.
|
|
299
|
+
|
|
300
|
+
## Errors and failure paths
|
|
301
|
+
|
|
302
|
+
Plan for these rather than assuming a happy path.
|
|
303
|
+
|
|
304
|
+
**A search with no matches returns a successful result with an empty `productResults` array**, not an error. `requestMetadata.status` is still `ok`. Test the array length before iterating.
|
|
305
|
+
|
|
306
|
+
**An ASIN that does not exist on the chosen marketplace answers with an error, not an empty product.** The same ASIN often exists on one domain and not another, so a failure on `www.amazon.de` does not mean the ASIN is wrong.
|
|
307
|
+
|
|
308
|
+
**A seller ID is marketplace-scoped too.** The ID that a product on `www.amazon.com` returns will not resolve on another domain.
|
|
309
|
+
|
|
310
|
+
**A price can be absent from a live listing.** Items that are out of stock, sold only through other sellers, or gated behind a promotion come back without a usable `currentPrice`. Read `isAvailable` before you compare prices.
|
|
311
|
+
|
|
312
|
+
**`deliveryZip` and `shippingLocation` change the answer, not just the delivery line.** Availability, price and the seller mix all shift with the destination, so a comparison across postcodes has to hold every other parameter still.
|
|
313
|
+
|
|
314
|
+
Results that carry data also carry a `requestMetadata.id` worth quoting in support.
|
|
315
|
+
|
|
316
|
+
## Pricing, free tier and limits
|
|
317
|
+
|
|
318
|
+
Each Amazon tool costs **5 credits per successful call**. Turning on `otherSellers` adds 5 credits to the product call, 10 instead of 5, so leave it off unless the competing offers are the point. Response size does not change the price.
|
|
319
|
+
|
|
320
|
+
The free tier is **1,000 credits every month with no card**, which is 200 Amazon calls at the base rate. It renews with the billing cycle, so a low-volume agent runs on the free tier indefinitely.
|
|
321
|
+
|
|
322
|
+
Paid plans start at **$49 a month** for 200,000 credits, which is 40,000 calls. The unit price falls with volume, from **$1.23 per 1,000 calls** on the entry plan to **$0.50** on Business, **$0.42** on Growth and **$0.37** on the largest [high-volume plans](https://hasdata.com/prices?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp).
|
|
323
|
+
|
|
324
|
+
Your plan also sets concurrency. The free tier allows 1 request at a time, Startup 15, Business 30, Growth 50, and the high-volume plans run from 200 to 1,500. Handle the overflow case defensively in anything unattended, because an agent that fans out across ASINs will reach the ceiling before you do.
|
|
325
|
+
|
|
326
|
+
A request that comes back non-200 is not billed. A successful call that finds nothing is still a call.
|
|
327
|
+
|
|
328
|
+
## Tool selection
|
|
329
|
+
|
|
330
|
+
Two rules cover most of it.
|
|
331
|
+
|
|
332
|
+
Start from what the prompt gives you. A keyword goes to the search tool, an ASIN goes straight to the product tool, and a seller ID goes to one of the two seller tools. Spending a search call to reach an ASIN you already have is the most common waste.
|
|
333
|
+
|
|
334
|
+
Then pick by depth. The search and seller-products tools return the same thin item shape, good for ranking, filtering and price sweeps across many products. The product tool is the only one that returns brand, features, variants, images and the seller, and it is the only one worth calling when the question is about a single item.
|
|
335
|
+
|
|
336
|
+
## How it compares
|
|
337
|
+
|
|
338
|
+
Amazon's own Product Advertising API is the official route to this data, and it is a different instrument.
|
|
339
|
+
|
|
340
|
+
| | Product Advertising API | This server |
|
|
341
|
+
| :--- | :--- | :--- |
|
|
342
|
+
| Eligibility | An approved Associates account with qualifying sales | An API key |
|
|
343
|
+
| Setup | Associates signup, tag, request signing | One header |
|
|
344
|
+
| Scope | Items you are approved to advertise | Any public listing page |
|
|
345
|
+
| Seller storefronts | Not returned | Two dedicated tools |
|
|
346
|
+
| Search sorting | Limited set | The six orders Amazon shows a shopper |
|
|
347
|
+
| Cost | Free, when you qualify | Paid past the free tier, 5 credits a call |
|
|
348
|
+
|
|
349
|
+
The row that decides it is eligibility. The Product Advertising API is built for affiliates and its access depends on sales you have already made, which rules it out for research, monitoring and anything an agent does on your behalf. When you do qualify and only need advertisable items, the official API is the better fit.
|
|
350
|
+
|
|
351
|
+
## FAQ
|
|
352
|
+
|
|
353
|
+
### Is there an official Amazon MCP server?
|
|
354
|
+
|
|
355
|
+
Amazon does not publish one. This one is maintained by HasData and reads public Amazon pages.
|
|
356
|
+
|
|
357
|
+
### What is an Amazon MCP server?
|
|
358
|
+
|
|
359
|
+
An MCP server exposes tools an AI client can call. This one turns Amazon search results, product pages and seller storefronts into JSON an agent can reason over, without a browser or a scraping library in your stack.
|
|
360
|
+
|
|
361
|
+
### Do I need an Amazon account or API key?
|
|
362
|
+
|
|
363
|
+
No. The only credential is your HasData key.
|
|
364
|
+
|
|
365
|
+
### Which marketplaces are covered?
|
|
366
|
+
|
|
367
|
+
All 23 domains the API accepts, from `www.amazon.com` through the European and Asian marketplaces. Pass `domain` to switch. Prices, availability and the seller mix differ per marketplace, so a cross-domain comparison is a real comparison rather than a currency conversion.
|
|
368
|
+
|
|
369
|
+
### Why does a search result have no brand or features?
|
|
370
|
+
|
|
371
|
+
Amazon does not put them on the results page. The search tool returns what the page shows, and the product tool returns the item page. That split is the reason the two tools cost the same and return different depths.
|
|
372
|
+
|
|
373
|
+
### What does `otherOfferQuantity` mean?
|
|
374
|
+
|
|
375
|
+
The number of other sellers offering the same item, as the product page reports it. It arrives with the base call. The offers themselves need `otherSellers`, which costs 5 credits more.
|
|
376
|
+
|
|
377
|
+
### Can I use this together with other HasData APIs?
|
|
378
|
+
|
|
379
|
+
Yes. One key covers everything, and one endpoint serves them all through the `apis` parameter. Point a client at `?apis=amazon,google_serp` to get both tool sets in one connection, or at [`mcp.hasdata.com/api/mcp`](https://docs.hasdata.com/mcp-server?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp) for the full catalogue.
|
|
380
|
+
|
|
381
|
+
### Is HasData affiliated with Amazon?
|
|
382
|
+
|
|
383
|
+
No. HasData is an independent service and is not affiliated with, endorsed by, or sponsored by Amazon. Amazon is a trademark of its respective owner. The tools work with publicly available data only, and you are responsible for using the results in line with Amazon's terms and the law that applies to you.
|
|
384
|
+
|
|
385
|
+
### Compliance and personal data
|
|
386
|
+
|
|
387
|
+
Seller profiles carry a business name and a business address, which are published by Amazon on the storefront page. Treat them as business records rather than free-form data, and check your own obligations before storing them.
|
|
388
|
+
|
|
389
|
+
## HasData links
|
|
390
|
+
|
|
391
|
+
- [Amazon Scraper API](https://hasdata.com/apis/amazon-api?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp), the REST endpoints behind these tools
|
|
392
|
+
- [API documentation](https://docs.hasdata.com/apis/amazon/search?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp)
|
|
393
|
+
- [MCP server documentation](https://docs.hasdata.com/mcp-server?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp)
|
|
394
|
+
- [Pricing](https://hasdata.com/prices?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp)
|
|
395
|
+
- [Dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=amazon-mcp)
|
|
396
|
+
|
|
397
|
+
Other HasData MCP servers: [Google Search](https://github.com/HasData/google-search-mcp), [Google Maps](https://github.com/HasData/google-maps-mcp), [Google Trends](https://github.com/HasData/google-trends-mcp), [Google Flights](https://github.com/HasData/google-flights-mcp), [DuckDuckGo](https://github.com/HasData/duckduckgo-mcp), [YouTube](https://github.com/HasData/youtube-mcp), [TikTok](https://github.com/HasData/tiktok-mcp), [Instagram](https://github.com/HasData/instagram-mcp), [Zillow](https://github.com/HasData/zillow-mcp), [Airbnb](https://github.com/HasData/airbnb-mcp), [Booking.com](https://github.com/HasData/booking-mcp), [Indeed](https://github.com/HasData/indeed-mcp).
|
|
398
|
+
|
|
399
|
+
## Development
|
|
400
|
+
|
|
401
|
+
The launcher is a thin stdio bridge to the remote server, so there is nothing to build.
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
npm install
|
|
405
|
+
HASDATA_API_KEY=your_key_here npm test
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
The tests in `test/` assert the tool contract, the part that can break without a commit here. They check that `?apis=amazon` returns the expected tool count, that no name changed, that every tool still declares its required parameter and carries a description, and that the key in use is actually accepted. That last check calls a tool for real and costs 5 credits, which is the price of a canary that can fail for the right reason.
|
|
409
|
+
|
|
410
|
+
One more test covers a tool this README does not document. The server also lists a reviews tool whose upstream endpoint is retired and answers with an error, so documenting it would send readers at a dead end. The test pins that state instead of ignoring it, and it fails the day the endpoint returns or the day the server drops the tool, which is when this README needs a decision.
|
|
411
|
+
|
|
412
|
+
The contract suite also runs weekly on a schedule, because the upstream tool list can change without anyone touching this repository.
|
|
413
|
+
|
|
414
|
+
## Contributing
|
|
415
|
+
|
|
416
|
+
A tool table, a response sample or a documented behaviour that does not match reality is worth an issue. There is a template for exactly that. Pull requests are welcome for the same, and for anything in the launcher.
|
|
417
|
+
|
|
418
|
+
## License
|
|
419
|
+
|
|
420
|
+
MIT, see [LICENSE](LICENSE).
|