{"_id":"@bintangtimurlangit/ebay-terapeak-mcp","_rev":"2-a9636a03d8897c076c38349b23e29d00","name":"@bintangtimurlangit/ebay-terapeak-mcp","dist-tags":{"latest":"0.2.1"},"versions":{"0.2.0":{"name":"@bintangtimurlangit/ebay-terapeak-mcp","version":"0.2.0","keywords":["mcp","model-context-protocol","ebay","terapeak","product-research","market-research","cli"],"license":"MIT","_id":"@bintangtimurlangit/ebay-terapeak-mcp@0.2.0","maintainers":[{"name":"bintangtimurlangit","email":"btimurlangit@gmail.com"}],"homepage":"https://github.com/bintangtimurlangit/ebay-terapeak-mcp#readme","bugs":{"url":"https://github.com/bintangtimurlangit/ebay-terapeak-mcp/issues"},"bin":{"ebay-terapeak-mcp":"dist/index.js"},"dist":{"shasum":"e4be7aaec17a302f6c020cc9a7ef3e3fe3d59f82","tarball":"https://registry.npmjs.org/@bintangtimurlangit/ebay-terapeak-mcp/-/ebay-terapeak-mcp-0.2.0.tgz","fileCount":18,"integrity":"sha512-BlxcTUjO0vCfdYThmItoOWvCoGQQiSy12K+XYX9Y12J8AejVqFacpCadCJ2rYHFiiFEzIkny0NPWiqDj0n+xqQ==","signatures":[{"sig":"MEYCIQCj/07k2/qwYjwqzfPU8eQrOPuK/Y1wB7MSTHJtYaNWrQIhAJmzO2M5RxBslEKX97iIVOw9/SIiwj+5R0AcSspD+4JU","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":63377},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"ba77c96752a651ea5c07850bf960f35641fd0fba","scripts":{"dev":"tsc -w","lint":"eslint .","build":"tsc","login":"npm run build && node dist/index.js login","start":"npm run build && node dist/index.js","format":"prettier --write .","prepare":"husky","lint:fix":"eslint . --fix","typecheck":"tsc --noEmit","format:check":"prettier --check .","prepublishOnly":"npm run build"},"_npmUser":{"name":"bintangtimurlangit","email":"btimurlangit@gmail.com"},"repository":{"url":"git+https://github.com/bintangtimurlangit/ebay-terapeak-mcp.git","type":"git"},"_npmVersion":"11.16.0","description":"MCP server + CLI that searches eBay Terapeak (Seller Hub Product Research) sold & active listings via a persistent CloakBrowser session.","directories":{},"lint-staged":{"*.ts":"eslint --fix","*.{ts,js,json,md,yml,yaml}":"prettier --write"},"_nodeVersion":"24.16.0","dependencies":{"zod":"^3.24.0","playwright":"^1.49.0","cloakbrowser":"^0.4.10","@modelcontextprotocol/sdk":"^1.12.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7","eslint":"^9.17.0","prettier":"^3.4.2","@eslint/js":"^9.17.0","typescript":"^5.7.0","@types/node":"^22.10.0","lint-staged":"^15.3.0","@commitlint/cli":"^19.6.1","typescript-eslint":"^8.19.0","eslint-config-prettier":"^9.1.0","@commitlint/config-conventional":"^19.6.0"},"_npmOperationalInternal":{"tmp":"tmp/ebay-terapeak-mcp_0.2.0_1784396024786_0.36285530409074385","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@bintangtimurlangit/ebay-terapeak-mcp","version":"0.2.1","description":"MCP server + CLI that searches eBay Terapeak (Seller Hub Product Research) sold & active listings via a persistent CloakBrowser session.","author":{"name":"bintangtimurlangit"},"license":"MIT","type":"module","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/bintangtimurlangit/ebay-terapeak-mcp.git"},"bugs":{"url":"https://github.com/bintangtimurlangit/ebay-terapeak-mcp/issues"},"homepage":"https://github.com/bintangtimurlangit/ebay-terapeak-mcp#readme","bin":{"ebay-terapeak-mcp":"dist/index.js"},"scripts":{"build":"tsc","login":"npm run build && node dist/index.js login","start":"npm run build && node dist/index.js","dev":"tsc -w","typecheck":"tsc --noEmit","lint":"eslint .","lint:fix":"eslint . --fix","format":"prettier --write .","format:check":"prettier --check .","prepare":"husky","prepublishOnly":"npm run build"},"lint-staged":{"*.{ts,js,json,md,yml,yaml}":"prettier --write","*.ts":"eslint --fix"},"keywords":["mcp","model-context-protocol","ebay","terapeak","product-research","market-research","cli"],"dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","cloakbrowser":"^0.4.12","playwright":"^1.49.0","zod":"^3.24.0"},"devDependencies":{"@commitlint/cli":"^21.2.1","@commitlint/config-conventional":"^21.2.0","@eslint/js":"^10.0.1","@types/node":"^22.20.1","eslint":"^10.7.0","eslint-config-prettier":"^10.1.8","husky":"^9.1.7","lint-staged":"^17.1.0","prettier":"^3.4.2","typescript":"^5.7.0","typescript-eslint":"^8.65.0"},"engines":{"node":">=18.0.0"},"gitHead":"56e7c26c88e969c39a1baeb68a8c045c31fb61b5","_id":"@bintangtimurlangit/ebay-terapeak-mcp@0.2.1","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-pf6+DqqNRPvk5OQH10iO3JXmHrLNAxw6ZLBpElsM5tEn3FYGnqVL+aYW6mrw58rgbkBd2rLWwAu1KRezonM/LQ==","shasum":"f2f0947b94d4a71eef3a80802dd3ab67b4d85d91","tarball":"https://registry.npmjs.org/@bintangtimurlangit/ebay-terapeak-mcp/-/ebay-terapeak-mcp-0.2.1.tgz","fileCount":18,"unpackedSize":64455,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bintangtimurlangit%2febay-terapeak-mcp@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDVK1IaEeL3cTWYRK9eSsGLaTHeVcawA1go6D2QjUGiygIgDOhqAvT9Vvh2T2hYD/pYVabCOUHxIs3tGFYbz4llcc0="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:931b8f6f-5753-4f61-8353-2776e35e5f38"}},"directories":{},"maintainers":[{"name":"bintangtimurlangit","email":"btimurlangit@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ebay-terapeak-mcp_0.2.1_1784596037365_0.8992724946685877"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-18T17:33:44.618Z","modified":"2026-07-21T01:07:17.890Z","0.2.0":"2026-07-18T17:33:44.911Z","0.2.1":"2026-07-21T01:07:17.545Z"},"bugs":{"url":"https://github.com/bintangtimurlangit/ebay-terapeak-mcp/issues"},"license":"MIT","homepage":"https://github.com/bintangtimurlangit/ebay-terapeak-mcp#readme","keywords":["mcp","model-context-protocol","ebay","terapeak","product-research","market-research","cli"],"repository":{"type":"git","url":"git+https://github.com/bintangtimurlangit/ebay-terapeak-mcp.git"},"description":"MCP server + CLI that searches eBay Terapeak (Seller Hub Product Research) sold & active listings via a persistent CloakBrowser session.","maintainers":[{"name":"bintangtimurlangit","email":"btimurlangit@gmail.com"}],"readme":"# ebay-terapeak-mcp\n\n[![npm](https://img.shields.io/npm/v/@bintangtimurlangit/ebay-terapeak-mcp?style=flat-square)](https://www.npmjs.com/package/@bintangtimurlangit/ebay-terapeak-mcp)\n[![license](https://img.shields.io/github/license/bintangtimurlangit/ebay-terapeak-mcp?style=flat-square)](./LICENSE)\n[![CI](https://img.shields.io/github/actions/workflow/status/bintangtimurlangit/ebay-terapeak-mcp/ci.yml?branch=main&style=flat-square)](https://github.com/bintangtimurlangit/ebay-terapeak-mcp/actions)\n[![GitHub Repo](https://img.shields.io/badge/GitHub-ebay--terapeak--mcp-24292f?style=flat-square&logo=github)](https://github.com/bintangtimurlangit/ebay-terapeak-mcp)\n\nAn MCP server **and CLI** that lets an AI agent (Claude, etc.) — or you, from the\nterminal — search eBay's **Terapeak \"Product Research\"** data (sold & active\nlistings) without opening the Seller Hub UI.\n\nIt wraps eBay's internal endpoint `GET /sh/research/api/search` and keeps a\n**persistent, logged-in [CloakBrowser](https://github.com/CloakHQ/cloakbrowser)\nsession** (a fingerprint-patched Chromium) alive so requests are made from inside\na real browser. That carries your session cookies, passes eBay's bot\ndetection (Akamai + perfdrive), and lets the browser rotate the short-lived\nanti-bot cookies itself — which is what avoids constant cookie-staleness.\n\n> ⚠️ **Unofficial.** This uses a private endpoint intended for the Seller Hub\n> web app, driven by your own logged-in session. It is not an eBay-supported API\n> and can break if eBay changes the endpoint. Use it for your own research and\n> keep request volume reasonable. For a supported alternative, see eBay's\n> **Marketplace Insights API**.\n\n**Full reference:** [Documentation](./docs/README.md) · **Changelog:** [CHANGELOG.md](./CHANGELOG.md) · **Versioning & releases:** [docs/RELEASES.md](./docs/RELEASES.md)\n\n---\n\n## Requirements\n\n- Node.js 18+ (tested on v24)\n- A display (or `xvfb` on a headless server) — the session runs a real browser\n- An eBay account with access to Seller Hub → Research\n\n## Setup\n\n### From npm (recommended)\n\n```bash\nnpm install -g @bintangtimurlangit/ebay-terapeak-mcp   # downloads the CloakBrowser binary (~200 MB, cached)\n```\n\nPuts the **`ebay-terapeak-mcp`** command on your PATH (it doubles as the CLI and,\nwith `login`, the one-time sign-in). Or run without installing:\n`npx -y @bintangtimurlangit/ebay-terapeak-mcp`.\n\n### From source\n\n```bash\ngit clone https://github.com/bintangtimurlangit/ebay-terapeak-mcp.git\ncd ebay-terapeak-mcp\nnpm install          # also downloads the CloakBrowser binary (~200 MB, cached)\nnpm run build\n```\n\n### One-time login\n\nSign into eBay once. This opens a real browser window and saves the session to a\npersistent profile (`~/.ebay-research-mcp/profile` by default).\n\n```bash\nebay-terapeak-mcp login      # global install — or, from a source checkout:  npm run login\n```\n\nSign in (complete any 2FA) and wait until the **\"Research products\"** page loads.\nThe window closes itself once login is detected.\n\n> The login step and the running server both use the same browser profile, and a\n> profile can only be open in one browser at a time. **Stop the MCP server before\n> running login.**\n\n## Use with Claude Code\n\nRegister the server:\n\n```bash\nclaude mcp add ebay-terapeak -- npx -y @bintangtimurlangit/ebay-terapeak-mcp\n```\n\nOr add it to your MCP config JSON:\n\n```json\n{\n  \"mcpServers\": {\n    \"ebay-terapeak\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bintangtimurlangit/ebay-terapeak-mcp\"]\n    }\n  }\n}\n```\n\nAfter a global install you can instead use `\"command\": \"ebay-terapeak-mcp\"`, `\"args\": []`. From a source checkout, use `\"command\": \"node\"`, `\"args\": [\"/ABSOLUTE/PATH/TO/ebay-terapeak-mcp/dist/index.js\"]`.\n\nThen ask, e.g.: _\"Search eBay sold listings for 'nintendo switch oled' over the\nlast 90 days.\"_\n\n## Tools\n\n| Tool                     | Description                                                |\n| ------------------------ | ---------------------------------------------------------- |\n| `search_sold_listings`   | Sold-listing research: aggregate stats + per-listing rows. |\n| `search_active_listings` | Same for currently-active listings.                        |\n| `session_status`         | Report whether the browser profile is still logged in.     |\n\n### Tool annotations\n\nPer the [MCP annotations spec](https://modelcontextprotocol.io/) — all tools are read-only, with no side effects.\n\n| Tool                     | Read-only | Idempotent | Destructive |\n| ------------------------ | :-------: | :--------: | :---------: |\n| `search_sold_listings`   |     ✓     |     ✓      |      –      |\n| `search_active_listings` |     ✓     |     ✓      |      –      |\n| `session_status`         |     ✓     |     ✓      |      –      |\n\n### Parameters (both search tools)\n\n| Param                     | Default      | Notes                                                           |\n| ------------------------- | ------------ | --------------------------------------------------------------- |\n| `keywords`                | —            | Search terms or a product id (MPN/UPC/EPID/EAN/ISBN).           |\n| `exact`                   | `false`      | Quote the phrase so eBay matches it exactly (big noise cut).    |\n| `exclude`                 | `[]`         | Terms to drop from results (client-side title match).           |\n| `condition`               | —            | `new` or `used` (server-side).                                  |\n| `min_price` / `max_price` | —            | Price range filter (server-side).                               |\n| `format`                  | `all`        | `auction`, `fixed`, or `all` (server-side).                     |\n| `sort`                    | `best_match` | `sales`, `units`, `price`, `price_asc`, `recent`, `best_match`. |\n| `summary_only`            | `false`      | Return only aggregate stats, no rows.                           |\n| `detail`                  | `false`      | Include heavy fields (`extendedTitle`, `moreImages`).           |\n| `days`                    | `90`         | Lookback window in days (max 1095 = 3 years).                   |\n| `category_id`             | `0`          | eBay category id; `0` = all.                                    |\n| `max_results`             | `50`         | Listings to return; paginated 50/page (max 500).                |\n| `marketplace`             | `EBAY-US`    | e.g. `EBAY-US`, `EBAY-GB`, `EBAY-DE`.                           |\n\n### Filters: server-side vs client-side\n\nThe endpoint honors some refinements as query params and ignores others. Which\nis which was verified empirically (by diffing result counts against the live\nendpoint), not assumed:\n\n- **Server-side** (narrows the data _and_ the aggregate stats): `exact` phrase,\n  `condition` (`conditionId`), `min_price`/`max_price` (`minPrice`/`maxPrice`),\n  `format` (`AUCTION`/`FIXED_PRICE`).\n- **Client-side** (applied here after fetch; aggregates still reflect the\n  unfiltered-by-these market): `exclude` (the endpoint returns _zero_ rows for\n  `-term` exclusion), `sort`, and de-duplication of repeated rows.\n\nSorting orders the rows actually retrieved (up to `max_results`), so raise\n`max_results` for a wider ranking.\n\n### Response shape\n\n```jsonc\n{\n  \"query\": { \"keywords\": \"...\", \"tab\": \"SOLD\", \"days\": 90, ... },\n  \"aggregates\": {\n    \"avgSoldPrice\": 117.78,\n    \"soldPriceRange\": \"$0.01 - $16,497.50\",\n    \"avgShipping\": 11.85,\n    \"freeShippingPct\": 73,\n    \"totalSold\": 247663,\n    \"sellThrough\": \"-\",\n    \"totalSellers\": 50063,\n    \"totalItemSales\": 29169748.14,\n    \"raw\": { \"Avg sold price\": \"$117.78\", ... }\n  },\n  \"resultCount\": 100,\n  \"results\": [\n    {\n      \"itemId\": \"366324079285\",\n      \"title\": \"For Nintendo Switch OLED/NS/Lite Console ...\",\n      \"extendedTitle\": \"...\",\n      \"url\": \"https://www.ebay.com/itm/366324079285...\",\n      \"imageUrl\": \"https://i.ebayimg.com/images/g/.../s-l1200.webp\",\n      \"moreImages\": [ \"...\" ],\n      \"format\": \"Fixed price\",\n      \"avgSoldPrice\": 11.27,\n      \"avgSoldPriceText\": \"$11.27\",\n      \"avgShipping\": 11.78,\n      \"freeShippingPct\": 96,\n      \"totalSold\": 486,\n      \"totalSales\": 5478.54,\n      \"totalSalesText\": \"$5,478.54\",\n      \"dateLastSold\": \"Jul 5, 2026\",\n\n      // ACTIVE-tab rows populate these instead of the sold-* fields above:\n      \"listingPrice\": null,\n      \"listingPriceText\": null,\n      \"listingShipping\": null,\n      \"watchers\": null,\n      \"promoted\": null,\n      \"startDate\": null,\n      \"bids\": null\n      // `extendedTitle` and `moreImages` appear only when detail=true\n    }\n  ],\n  \"pagination\": { \"summary\": \"Results: 1 - 50\", \"currentPage\": 1, \"hasNext\": true },\n  \"notes\": [ \"Aggregates reflect the server-side filters ...\", \"...\" ]\n}\n```\n\n> **SOLD** rows carry `avgSoldPrice` / `totalSold` / `totalSales` / `dateLastSold`;\n> **ACTIVE** rows carry `listingPrice` / `watchers` / `promoted` / `startDate`.\n> The other tab's fields are `null`. Rows are **compact by default** (no\n> `extendedTitle`/`moreImages`) to keep responses small — pass `detail: true` to\n> include them.\n\n## CLI\n\nThe same search engine is available from the terminal (no MCP client needed):\n\n```bash\nnode dist/index.js search \"Players Pins\" --exact --sort sales --limit 15\nnode dist/index.js search \"Players Pins\" --active --exact --min-price 20 --max-price 60\nnode dist/index.js search \"Players Pins\" --exact --condition new --summary\nnode dist/index.js search \"Players Pins\" --exact --json > results.json\n```\n\nRun `node dist/index.js search --help` for all flags. Flags map 1:1 to the tool\nparams above (`--min-price`/`--max-price`, `--limit` = `max_results`,\n`--category` = `category_id`, `--sold`/`--active` pick the tab). `--json` emits\nthe full structured result; otherwise a compact table is printed.\n\n## Configuration (env vars)\n\n| Var                 | Default                        | Purpose                                                 |\n| ------------------- | ------------------------------ | ------------------------------------------------------- |\n| `EBAY_MCP_PROFILE`  | `~/.ebay-research-mcp/profile` | Browser profile dir (holds your session).               |\n| `EBAY_MCP_HEADLESS` | `1`                            | Set `0` to run headed if bot detection blocks headless. |\n| `EBAY_MCP_TZ`       | `UTC`                          | Timezone string sent to eBay (e.g. `Asia/Jakarta`).     |\n\n## Troubleshooting\n\n- **`NotLoggedInError` / \"non-JSON response\"** — session expired or got flagged.\n  Stop the server, run `npm run login`, restart.\n- **Headless getting blocked** — set `EBAY_MCP_HEADLESS=0` in the MCP server env.\n- **`profile ... already in use`** — the server and the login command can't run\n  at the same time. Stop one.\n\n## Layout\n\n```\nsrc/\n  index.ts    entry: `login` / `search` (CLI) commands vs. start server\n  browser.ts  persistent Playwright session (login + in-page fetch)\n  parse.ts    deep mapping of eBay's module/TextualDisplay JSON -> flat objects\n  core.ts     framework-agnostic search engine: query build, filters, pagination\n  server.ts   MCP server + tool schemas (thin wrapper over core)\n  cli.ts      CLI front-end (arg parsing + table output over core)\nreference/\n  ebay_terapeak.py   standalone cookie-replay script (no browser) — reference only\n```\n\n## Development\n\nLint, format, typecheck, and build with `npm run lint`, `npm run format`, `npm run typecheck`, and `npm run build`. Full guide: **[docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md)**.\n\n## Contributing & security\n\n[CONTRIBUTING.md](./CONTRIBUTING.md) · [SECURITY.md](./SECURITY.md) · [Code of Conduct](./CODE_OF_CONDUCT.md)\n\n## License\n\n[MIT](./LICENSE)\n\n---\n\n## Disclaimer\n\nThis is an **unofficial** project. It is **not affiliated with, authorized, maintained, sponsored, or endorsed by eBay Inc.**\n\nIt drives a **private endpoint** intended for the Seller Hub web app via your own logged-in session; it is not an eBay-supported API and can break if eBay changes the endpoint or its bot detection. For a supported alternative, see eBay's **Marketplace Insights API**. It reads only research data your account can already access and performs no account actions.\n\nYou are responsible for using this software in compliance with [eBay's User Agreement](https://www.ebay.com/help/policies/member-behaviour-policies/user-agreement) and applicable law. Keep request volume reasonable. All product names, logos, and brands are property of their respective owners.\n","readmeFilename":"README.md","author":{"name":"bintangtimurlangit"}}