oskelly-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@oskelly-mcp search for women's jackets under 5000 rubles"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
oskelly-mcp
MCP server for the public catalog of oskelly.ru. 14 tools, anonymous read-only operations only, all verified against the live site.
Unofficial project, not affiliated with Oskelly. Reads exactly what any visitor without registration sees. Trademarks belong to their respective owners.
License
Related MCP server: VkusVill MCP Server
Installation
Node.js 22+.
git clone https://github.com/ihavealotofguap/oskelly-mcp.git
cd oskelly-mcp
npm ci
npm run build
npm run verifyClaude Desktop —
claude_desktop_config.json(Settings → Developer → Edit Config), the path must be absolute:{ "mcpServers": { "oskelly": { "command": "node", "args": ["/abs/path/oskelly-mcp/dist/index.js"] } } }spawn node ENOENTon Windows → replace"node"with the output ofwhere node, escape the slashes.After editing, fully restart the app, including the tray icon.
Claude Code —
claude mcp add oskelly -- node /abs/path/oskelly-mcp/dist/index.jsDebugging —
npm run inspector
Tools
Tool | What it does |
| Cheat sheet for the filter model: codes, formats, how to resolve a name into an id |
| Search: query, facets, price, boolean tags, pagination, sorting |
| Same query, but returns counts and available facets instead of products |
| Values of a single facet with ids ( |
| Query autocomplete |
| Category tree, trimmed by |
| Brands with ids, substring search, pagination |
| Product conditions with descriptions |
| Attribute dictionary (material, color, …) |
| Product card by id or URL: description, attributes, sizes, photos, seller |
| Seller's products |
| What actually exists in the seller's assortment |
| Homepage banners (FEMALE/MALE/KIDS/LIFESTYLE) |
| Expands a banner collection into a filter preset + products |
Flow: describe_filters → list_brands/category_tree/filter_values → search_products → get_product.
Scope
There is and can be no login, cookies, cart, favorites, messages, or orders. This is a property of the code:
credentials: "omit", noAuthorization/Cookieheaders.POST is allowed only for three read-only search endpoints — the allow-list
assertReadOnlyPostinsrc/client.ts.All tools:
readOnlyHint: true,destructiveHint: false.A smoke test verifies that the tools list contains no names with
login/cart/favourite/order/checkout/message/account.
Notes
The product card is parsed from
__NUXT_DATA__. There is no public JSON endpoint for a single product (GET /api/v2/products/{id}→ 404), the page is rendered by Nuxt 3 on the server. The payload is decoded with the officialdevaluepackage — the same library Nuxt uses to serialize it; custom types are wired in through the standard revivers (src/nuxt.ts). Not Playwright: ~150 MB of Chromium and 3–5 s versus a single GET in ~150 ms.The slug in the URL is ignored — only the numeric id at the end matters, the tool accepts both.
Filter format in the
/products/search*body: multi-select is an array of ids ({"brand": [675]}), boolean is a bare boolean ({"sale": true}), price is an object ({"price": {"lower": 50000}}).{"brand": "675"}and{"sale": [true]}are silently ignored,{"price": [a, b]}yieldssuccess: false.Price is filtered by the size-SKU, not by the card price — a product can appear in results with a card price below the boundary, so every response carries
sizePriceRange: {min, max}.Upstream counters are renamed:
totalAmount→totalMatches,itemsCount→itemsOnPage.Segments (
baseCategory) are tree node ids: Women=2, Men=105, Kids=188, Lifestyle=366.WAF: Cyrillic in the query must be percent-encoded, otherwise 403.
Context: raw responses are huge (the tree is ~1 MB, brands ~750 KB), so a compact projection is returned by default;
verbose: truereturns the untouched response.
Testing
npm run verify # офлайн: сервер стартует, 14 tools, все read-only
node smoke-test.mjs # живой end-to-end по MCP против oskelly.ruThe smoke test launches the compiled server as a separate process over stdio and exercises every tool
against the live site — no mocks. Parameters are chained from previous responses
(brand → search → productId → sellerId → banner), and each call passes a meaningful check:
PRICE_DESC really yields descending prices, conditionIds: [1] really yields only condition 1,
filters narrow the results monotonically. The latest run is SMOKE-TEST-OUTPUT.txt
(23 calls, 14/14 tools, 0 failures).
CI builds the project on Node 22/24/26 and runs npm run verify. The live smoke test is moved to a manual
run (Actions → CI → Run workflow → run_smoke_test) so as not to hammer a third-party site from runners.
Structure
src/client.ts HTTP-клиент, конверт, allow-list на POST
src/nuxt.ts извлечение и декодирование SSR-payload (devalue)
src/search.ts схема и сборка тела запроса для /products/search*
src/format.ts компактные проекции ответов
src/tools.ts определения 14 инструментов
src/index.ts точка входа, stdio-транспорт
scripts/verify-server.mjs офлайн-проверка поверхности tools (CI)
smoke-test.mjs живой end-to-end тест по протоколу MCPContributing
PRs are welcome. Before submitting — npm run build, npm run verify, node smoke-test.mjs.
The most fragile spots if oskelly updates: the __NUXT_DATA__ format (it will fail with an explicit error
pointing to adding a reviver in src/nuxt.ts), facet codes, segment ids. Rate-limiting
has not been tested; 45 s timeout, no retries — deliberately.
Available Tools
14 toolsoskelly_banner_catalogResolve a banner/curated selection to productsARead-onlyIdempotent
Open an oskelly.ru curated-selection page (a banner's catalogLink, e.g. https://oskelly.ru/catalog/bannerV2/) and return its title, the filter preset it encodes (for example a specific seller's wardrobe), the total item count and the first page of products. Curated pages are rendered server-side, so this reads the page's Nuxt payload rather than an API endpoint.
Inputs: catalogLink (required), verbose.
oskelly_category_treeCategory treeARead-onlyIdempotent
Return the oskelly.ru category tree. The root (id 1, 'Каталог') has the four top-level segments as children — their ids are real tree node ids read from the live tree, not a fixed enum. Use rootId to zoom into a subtree and depth to control how many levels come back (the full tree is ~618 nodes / 1 MB, so keep depth small). Category ids from here feed oskelly_search_products categoryIds and baseCategory.
Inputs: depth, rootId, verbose.
oskelly_describe_filtersExplain the filter modelARead-onlyIdempotent
Return a cheat-sheet of every filter code this server understands, how values are encoded, and which tool resolves names to ids. Call this once at the start of a browsing session instead of guessing filter names.
Inputs: no named parameters.
oskelly_filter_valuesList values of one facetARead-onlyIdempotent
List the selectable values (with their ids) of a single facet, scoped to the same search context. This is how you resolve a human name to the numeric id that oskelly_search_products expects — e.g. code='brand' to find the id of GUCCI, code='size' to find size value ids for the current category. Accepts every search parameter so the returned values reflect the narrowed result set.
Inputs: code (required), page, limit, price, +17 more.
oskelly_get_productGet product detailARead-onlyIdempotent
Fetch the full detail of a single oskelly.ru product by numeric id or product URL: description, condition, all attributes (material/colour/...), full size chart with per-size stock and pricing, breadcrumbs, every image, tags, and the seller's public profile. NOTE: oskelly.ru has no public JSON endpoint for a single product (/api/v2/products/{id} returns 404), so this reads the server-rendered Nuxt payload embedded in the product page and decodes it with the official devalue library.
Inputs: product (required), verbose.
oskelly_home_bannersHomepage bannersARead-onlyIdempotent
Return the promotional banners / curated selections shown on the oskelly.ru homepage for a given audience segment: title, description, image, and the catalog link that opens the underlying selection. Feed a banner's catalogLink into oskelly_banner_catalog to see what products it actually resolves to.
Inputs: category.
oskelly_list_attributesList product attributesARead-onlyIdempotent
List the product attribute dictionary (material, colour, style, ... ) with every possible value and its id. These are the attributes shown on a product card as 'Материал', 'Цвет' etc. Filter by name/code to keep the response small.
Inputs: limit, nameContains, includeValues.
oskelly_list_brandsList brandsARead-onlyIdempotent
List brands available on oskelly.ru with their numeric ids (needed for the brandIds search filter), url slugs and transliterated Russian names. The full list is ~7000 brands, so filter with nameContains or page through with limit/offset.
Inputs: limit, offset, nameContains, includeHidden.
oskelly_list_conditionsList product conditionsARead-onlyIdempotent
List the product condition grades used on oskelly.ru (id, name and the full Russian explanation of what each grade guarantees). Condition ids feed the conditionIds filter.
Inputs: no named parameters.
oskelly_search_facetsGet result count and available facetsARead-onlyIdempotent
Run the same search as oskelly_search_products but return the total result count plus the list of facets available for that result set (their codes, names, types, hot values and the price range present) instead of the products. Use this to discover which filters make sense before drilling down, or to count matches cheaply without fetching items.
Inputs: page, price, query, sizeIds, +14 more.
oskelly_search_productsSearch productsARead-onlyIdempotent
Search the oskelly.ru luxury marketplace catalog and return matching product cards (id, brand, category, price, discount, condition, in-stock sizes, seller, image, URL). Supports full-text query, faceted filtering (brand, category, size, condition, collection, model, seller type, boutique, price range, boolean tags such as sale/vintage/outlet), pagination and sorting. Use oskelly_search_facets first when you need to know which filter values are available, and oskelly_filter_values to resolve names to ids.
Inputs: page, price, query, sizeIds, +14 more.
oskelly_search_suggestionsSearch autocompleteARead-onlyIdempotent
Get search-query autocomplete suggestions from oskelly.ru for a partial user query. Useful for discovering how the marketplace phrases things (brand + item combinations) before running a full search.
Inputs: userQuery (required), size.
oskelly_seller_filtersGet a seller's available filtersARead-onlyIdempotent
Return the sets of ids that actually occur in one seller's inventory — which attribute values, categories, brands, sizes and conditions they carry. Use it to understand a seller's assortment before filtering their catalog.
Inputs: sellerId (required), verbose.
oskelly_seller_productsList a seller's productsARead-onlyIdempotent
List the products currently offered by a specific oskelly.ru seller (boutique, brand or private seller), with pagination and sorting. Seller ids come from the seller block of any product card or from oskelly_get_product.
Inputs: sellerId (required), page, sorting, verbose, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct resource or action: search, facet discovery, filter value resolution, autocomplete, category tree, dictionary lookups, product detail, seller queries, and banner catalogs. Even the two facet-related tools are explicitly differentiated by what they return.
The dominant pattern is oskelly_<verb>_<object> (search_products, list_brands, get_product, describe_filters). A few names omit the verb (seller_products, home_banners, banner_catalog), but they are still predictable and readable.
14 tools is within the well-scoped range and each one covers a meaningful browsing need, from category and dictionary lookups to search, product detail, seller inventory, and curated banners. No tool feels redundant.
The read-only marketplace browsing surface is well covered: discovery via suggestions/categories/brands/conditions/attributes, faceted search, product detail, seller-focused queries, and banner-driven curated catalogs. The filter cheat-sheet and facet/filter value tools close the gap between filter names and the ids that search_products expects.
Related MCP Connectors
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
MCP server for Product Management
MCP server for ua_e_commerce_price_tracker_mcp
Remote MCP server for product discovery catalog and retrieving product details.
Related MCP Servers
- AlicenseCqualityBmaintenanceMCP server for MoySklad (МойСклад) warehouse and CRM management API. 21 tools covering the full order lifecycle: products, stock, counterparties, customer orders, shipments, supplies, warehouses, organizations, reports, and webhooks.6070 npm10MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for VkusVill grocery store, enabling product search, details retrieval, and cart link creation.4-
- AlicenseAqualityDmaintenanceA UCP-compliant MCP storefront server that exposes product catalog operations (search, cart, checkout) as MCP tools, following UCP schema version 2026-04-08.5MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that turns Wildberries marketplace into a toolkit for LLM agents, enabling product search, detailed card inspection, price history, reviews, and cross-product comparison.-