SmartScout Adapter

Brought to you by SkillCrate — the open-source marketplace for Amazon seller agent skills.

Standalone MCP server + OpenClaw-style library wrapper for the official SmartScout API.

This repo follows the same adapter premise as datadive-adapter: normalize SmartScout responses into a consistent, agent-readable envelope so Claude, ChatGPT, Helm, or any MCP client can consume them predictably.

Source Docs

• https://www.smartscout.com/smartscout-api
• https://api.smartscout.com/index.html
• https://api.smartscout.com/swagger/api/swagger.json

Current Tool Surface

• smartscout_search_brands
• smartscout_get_brand_market_share
• smartscout_get_brand_sellers
• smartscout_search_products
• smartscout_get_product_history
• smartscout_search_sellers
• smartscout_get_seller_brands
• smartscout_search_subcategories
• smartscout_get_subcategory_brands
• smartscout_search_terms
• smartscout_get_relevant_products
• smartscout_get_relevant_search_terms
• smartscout_estimate_sales

Quick Start

cd smartscout-adapter
npm install
npm run build

Install Via Claude Desktop MCPB

The easiest Claude Desktop install path is the .mcpb bundle from GitHub Releases.

1. Download smartscout-adapter-vX.Y.Z.mcpb from the latest release.
2. Open the .mcpb file with Claude Desktop.
3. Enter your SmartScout API key when Claude asks for SmartScout API Key.
4. Enable or restart the extension if Claude Desktop prompts you.
5. Start a new Claude chat and confirm the SmartScout tools are available.

The bundle passes your key to the local MCP server as SMARTSCOUT_API_KEY. The adapter still runs locally; SmartScout API calls go to SmartScout's API.

Build A Local MCPB

npm install
npm run mcpb:validate
npm run mcpb:pack

The packaged bundle is written to:

release/smartscout-adapter-v1.1.0.mcpb

Install Via Manual MCP

Install From GitHub Source

git clone https://github.com/BWB03/smartscout-adapter.git
cd smartscout-adapter
npm install
npm run build

This produces the MCP server entrypoint at:

./dist/index.js

MCP Server Command

The adapter runs as a stdio MCP server:

node /absolute/path/to/smartscout-adapter/dist/index.js

Required Environment

The MCP server requires:

SMARTSCOUT_API_KEY=your_api_key_here

Claude Desktop MCP Config

If you prefer manual JSON config instead of the .mcpb installer, add this server to Claude Desktop's MCP settings:

{
  "mcpServers": {
    "smartscout": {
      "command": "node",
      "args": ["/absolute/path/to/smartscout-adapter/dist/index.js"],
      "env": {
        "SMARTSCOUT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving the config.

Claude Code / Codex Setup

Claude Code, Codex, and other stdio MCP clients can use the same local server command after building from source:

{
  "mcpServers": {
    "smartscout": {
      "command": "node",
      "args": ["/absolute/path/to/smartscout-adapter/dist/index.js"],
      "env": {
        "SMARTSCOUT_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Codex CLI-style configs, use the equivalent command/args/env shape supported by your client:

[mcp_servers.smartscout]
command = "node"
args = ["/absolute/path/to/smartscout-adapter/dist/index.js"]

[mcp_servers.smartscout.env]
SMARTSCOUT_API_KEY = "your_api_key_here"

Generic MCP Client Config

Any MCP client that supports stdio servers can use the same command:

{
  "smartscout": {
    "command": "node",
    "args": ["/absolute/path/to/smartscout-adapter/dist/index.js"],
    "env": {
      "SMARTSCOUT_API_KEY": "your_api_key_here"
    }
  }
}

Update Flow

When you pull a new version from GitHub:

git pull
npm install
npm run build

For MCPB releases, download and install the newer .mcpb file from GitHub Releases.

Environment

Variable	Required	Default	Description
SMARTSCOUT_API_KEY	Yes	—	SmartScout API key
SMARTSCOUT_RATE_LIMIT_RPS	No	2	Requests per second
SMARTSCOUT_RATE_LIMIT_BURST	No	10	Burst limit
SMARTSCOUT_TIMEOUT_MS	No	30000	Request timeout in milliseconds
SMARTSCOUT_PRODUCT_HISTORY_TIMEOUT_MS	No	90000	Timeout override for smartscout_get_product_history

Request Pattern

Search-style tools accept:

• marketplace
• page_id
• page_size
• sort_by
• sort_order
• filters

filters must use official SmartScout top-level field names. Invalid filter keys are rejected client-side with a smartscout_validation error instead of being silently passed through.

Example:

{
  "filters": {
    "brandName": {
      "type": "contains",
      "filter": "Nike"
    },
    "monthlyRevenue": {
      "min": 50000
    }
  },
  "marketplace": "US",
  "page_size": 25
}

Common gotchas now caught client-side:

• For one exact ASIN, prefer asin
• If you use asins, send asins: { "filter": ["ASIN"] } or a bare array the adapter can coerce
• Do not use asinList
• Use amazonSellerId or amazonSellerIds, not sellerId
• Use searchTermValue, not searchTerm
• For subcategory-brand sorting, use revenue, not monthlyRevenue

Known-Good Fields

Examples of known-good filter keys by tool:

• smartscout_search_products: asin, asins, brandName, categoryName, subcategoryName, subcategoryId, rank, monthlyRevenueEstimate, reviewCount, reviewRating, buyBoxPrice, productPageScore, numberOfSellers, numberFbaSellers, outOfStockNow, isVariation, parentAsin, title, upc, listedSince For a single exact product lookup, asin is the simplest and most reliable form.
• smartscout_search_sellers: amazonSellerId, amazonSellerIds, sellerName, sellerNames, businessName, businessNames, categoryName, subcategoryName, estimateSales, percentFba, numberWinningBrands, numberAsins, numberTopAsins, numberReviewsLifetime, numberReviews30Days, city, state, country, zipCode, isSuspended
• smartscout_search_terms: searchTermValue, estimateSearches, estimatedCpc, brands, products, superCharge

Examples of known-good sort_by values:

• smartscout_get_subcategory_brands: revenue, marketshare, avgPrice, avgVolume, totalReviews, totalNumberUnitsSold, numberASINs, reviewRating, adSpendShare
• smartscout_get_product_history: date, salesRank, buyBoxPrice, newFbaPrice, newFbmPrice, reviewsCount, newOfferCount

Output Pattern

Every response uses the same normalized envelope:

{
  "source": "smartscout",
  "adapter_version": "1.0.0",
  "data_type": "brand_summary",
  "marketplace": "US",
  "retrieved_at": "2026-04-22T23:00:00.000Z",
  "pagination": {
    "next_page_id": null,
    "has_more_records": false,
    "data_count": 25,
    "page_size": 25
  },
  "data": []
}

Development

npm test
npm run build
npm run mcpb:validate
npm run mcpb:pack
SMARTSCOUT_API_KEY=xxx npm run test:integration

MCPB Release Flow

Version tags create GitHub Releases with the packaged .mcpb attached:

git tag v1.1.0
git push origin v1.1.0

The release workflow runs tests, builds the adapter, validates the MCPB manifest, packs the bundle, and uploads release/*.mcpb as a release asset.

MCPB Test Checklist

• Run npm test.
• Run npm run build.
• Run npm run mcpb:validate.
• Run npm run mcpb:pack.
• Confirm release/smartscout-adapter-v1.1.0.mcpb exists.
• Open the .mcpb file with Claude Desktop.
• Enter SMARTSCOUT_API_KEY in the install form.
• Confirm SmartScout tools appear in Claude Desktop.
• Run a low-cost brand or product search.
• Temporarily install with a missing or invalid key and confirm the adapter returns a clear SmartScout/API-key error rather than crashing.
• Push a version tag and confirm the GitHub Action attaches the .mcpb to the release.

Troubleshooting

• Claude Desktop does not show the tools: restart Claude Desktop, confirm the extension is enabled, and reinstall the .mcpb if needed.
• Missing API key errors: reinstall or edit the extension configuration and enter a valid SmartScout API key.
• Invalid SmartScout key or unauthorized responses: verify the key works against SmartScout directly and has access to the API endpoints you are calling.
• Node/runtime errors: use the .mcpb install path when possible. For manual installs, confirm node --version is 18 or newer.
• Build output looks stale: run npm run build, then npm run mcpb:pack again.
• Network/API failures: confirm the machine running Claude Desktop can reach https://api.smartscout.com.
• Manual JSON config does not work: use an absolute path to dist/index.js, keep command as node, and restart the MCP client after editing config.

Live Validation

This adapter has been live-tested against SmartScout with:

• brand search
• search term search
• product search
• product history for B01MCWCHR8
• validation rejection for bad filter keys and bad sort keys

The live integration test is in tests/integration/live-api.test.ts.

Notes

• SmartScout pagination is cursor-based, so the adapter returns next_page_id instead of page numbers.
• Page size is capped at 1000.
• Default rate limiting matches the SmartScout guidance you shared: 2 requests/second, burst 10.
• smartscout_get_product_history now uses a longer timeout, but SmartScout appears to return full history even when page_size is provided. Treat it as a full-history fetch until their API proves otherwise.
• The next step after validating this repo with your key is wiring SmartScout into Helm as a BYO source.