Apiguru MCP Server
Live Amazon marketplace data for AI agents — product details, reviews, keyword search, best-sellers, deals, live offers and stock, and seller profiles across 23 country marketplaces.
No API key required. Unkeyed callers get a small free probe budget, then an x402 payment challenge payable in USDC on Base, Polygon, Arbitrum or Avalanche. Bring an API key if you already have one and calls bill to your account instead.
Paying without leaving MCP. The challenge comes back as the
x402 MCP transport's
PaymentRequired tool result (isError, with x402Version and accepts in
structuredContent). An x402-capable MCP client pays it by resending the same
tool call with the payment in _meta["x402/payment"], and gets the settlement
receipt in the result's _meta["x402/payment-response"]. Nothing is settled
unless the call is answered. An agent without a wallet can ask its user to
connect https://mcp.apiguru.app/account and sign in; the same call then
bills their account.
Install
No install step is required: uvx fetches apiguru-mcp from PyPI and caches
it on first launch. (pip install apiguru-mcp works too, and so does running
straight from this repository: uvx --from "git+https://github.com/apiguru-app/agent-kit#subdirectory=mcp" apiguru-mcp.)
uvx apiguru-mcp
No Python or uv on the machine? npx -y apiguru-mcp (Node 18+) runs a stdio
bridge to the hosted server with the same 12 tools; see ../npm/README.md.
Claude Code
# remote (nothing to run locally):
claude mcp add --transport http apiguru https://mcp.apiguru.app/mcp
# or the plugin, which also carries the skill:
/plugin marketplace add apiguru-app/agent-kit
/plugin install apiguru@apiguru
Codex CLI
codex mcp add apiguru --url https://mcp.apiguru.app/mcp
# or locally:
codex mcp add apiguru -- uvx apiguru-mcp
Hermes Agent / OpenClaw / any stdio client
{
"mcpServers": {
"apiguru": {
"command": "uvx",
"args": ["apiguru-mcp"],
"env": { "APIGURU_API_KEY": "optional-key-here" }
}
}
}
Drop the env block entirely to run keyless.
claude.ai, Claude Desktop connectors, ChatGPT connectors
https://mcp.apiguru.app/account
Add it as a custom connector. The client discovers the OAuth 2.1 authorization server, registers itself, and sends you to a sign-in page where you use your Apiguru dashboard e-mail and password or paste an API key (Google sign-in accounts use the key). Every call then bills your account at your plan's rates. Disconnect from the client to revoke.
These clients cannot send headers, so signing in is how they bill your own account; the keyless endpoint below is meant for clients that can.
Remote, keyless (Claude Code, Codex, Hermes, any agent that can send headers)
https://mcp.apiguru.app/mcp
Streamable HTTP. Send X-API-KEY if you have one; omit it to go keyless.
Tools
| Tool | Does | Price |
|---|---|---|
list_capabilities |
Endpoints, prices, marketplaces | free, no network call |
product_details |
Full record for one ASIN | $0.003 |
product_details_batch |
Up to 20 ASINs at once | $0.0024/item |
product_reviews |
Reviews, rating, "customers say" | $0.003 |
search |
Keyword search with filters and sorting | $0.003 |
offers_stock |
Offers, buy box, live stock (≤10 ASINs) | $0.0045/item |
best_sellers |
Category rankings | $0.003 |
deals |
Current discounts with filters | $0.003 |
seller_profile_batch |
Seller profiles (≤10 IDs) | $0.0036/item |
seller_products |
A seller's catalogue | $0.003 |
seller_reviews |
Seller feedback | $0.003 |
Prefer the batch tools over looping the single-item ones — one round trip
instead of N, and cheaper per item without an account. The
product_details_batch record has no best-seller ranks, category path or
merchant id; use product_details per ASIN when you need those.
Error semantics worth knowing
Some errors cost money and some do not:
- 404 — the item genuinely isn't on that marketplace. Billed. Retrying
won't help; try a different
geo. - 503 — a temporary Apiguru-side failure. Not billed. Retry. On the
keyless path a free probe spent on a 503 is handed back, and a signed x402
payment is left unsettled (
X-Payment-Status: not-settled). - 429 — rate limit. Back off and retry.
- 413 — too many items in a batch (20 ASINs for
product_details_batch, 10 foroffers_stockandseller_profile_batch). Not billed; split the list. - 400 — bad input (an ASIN is 10 letters and digits; an Amazon product URL works in its place, and lower case is fine). Not billed.
Configuration
| Variable | Default | Purpose |
|---|---|---|
APIGURU_API_KEY |
unset | Use the keyed API instead of the keyless gateway |
APIGURU_BASE_URL |
from spec | Override the API base (self-hosted/staging) |
APIGURU_MCP_ALLOWED_HOSTS |
mcp.apiguru.app,localhost,127.0.0.1 |
Hosts the HTTP transport accepts. Must include the public hostname when running behind a reverse proxy, or every request is rejected with 421. |
APIGURU_MCP_ALLOWED_ORIGINS |
derived | CORS/DNS-rebinding origin allowlist |
APIGURU_MCP_STATELESS |
true |
Stateless streamable HTTP. Keep it on: in stateful mode the SDK snapshots each session's request context at initialize, so a key sent on a later request would be ignored. |
APIGURU_AGENT_INTERNAL_URL |
unset | Hosted deployments only: the gateway's address on the private network. With AGENT_INTERNAL_TOKEN set, keyless calls go there and carry the real caller's address. |
APIGURU_OAUTH_ENABLED |
false |
Hosted deployments only: mount the OAuth 2.1 endpoint at /account (needs DATABASE_URL; tokens are stored hashed in mcp_oauth_* tables). |
APIGURU_MCP_PUBLIC_URL |
from spec | The OAuth issuer, e.g. https://mcp.apiguru.app. |
APIGURU_API_INTERNAL_URL |
unset | Hosted deployments only: the backend on the private network, used for keyed calls and for proxying password logins to its /login. |
APIGURU_OAUTH_ACCESS_TTL / APIGURU_OAUTH_REFRESH_TTL |
1 day / 30 days | Token lifetimes in seconds. Refresh tokens rotate. |
Running the HTTP server yourself
pip install "apiguru-mcp[http]"
apiguru-mcp --http --host 0.0.0.0 --port 8790
Also serves /health, /llms.txt and /spec.json unauthenticated.
Development
Tools are generated from apiguru_mcp/data/endpoints.json, which is written by
agent-kit/spec/generate.py from the canonical spec. To add or change an
endpoint, edit agent-kit/spec/endpoints.json and re-run the generator — the
MCP tools, the OpenAPI document and llms.txt all update together.
python agent-kit/spec/generate.py
Links
- API docs: https://dash.apiguru.app/docs
- OpenAPI spec: https://dash.apiguru.app/openapi.json
- Get an API key: https://dash.apiguru.app/register
1 maintainer
Metadata
1 maintainer
Release files for apiguru-mcp 1.1.54
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| apiguru_mcp-1.1.54.tar.gz | 77.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| apiguru_mcp-1.1.54-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 164.0 kB
Release files / apiguru_mcp-1.1.54.tar.gz
| Download URL | apiguru_mcp-1.1.54.tar.gz |
|---|---|
| Size | 77.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
50a71d8f237db99da519807b8f48b0507fb6d0844ad3d6b221398e95c99f680d
|
|
BLAKE2b-256 checksum How to use checksums |
57f776f60152acce2c567e65cfeaae3ab504fa090f11d4726f6c7e1e25d0925b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / apiguru_mcp-1.1.54-py3-none-any.whl
| Download URL | apiguru_mcp-1.1.54-py3-none-any.whl |
|---|---|
| Size | 86.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c192976bd3eaabca23cfe59cb71bfe57f6ed1e0550c38314134ff31c27ea794a
|
|
BLAKE2b-256 checksum How to use checksums |
94e31e5a073d6d2b5347fe6c10ae97fd3b6f7ed9f94010bcd7ecf4b21ee2a9ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
