shoper-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., "@shoper-mcp find wireless headphones in the catalog and check their prices and stock"
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.
shoper-mcp
Serwer MCP (Model Context Protocol) tylko do odczytu katalogu sklepu na platformie Shoper. Agent AI (Claude Code, Claude Desktop, inny klient MCP) może przeszukać produkty, obejrzeć drzewo kategorii, sprawdzić stany i ceny oraz listę producentów. Nic więcej.
Read-only MCP server for a Shoper store catalog: products, categories, stock and prices, producers. No writes, no orders, no customers.
Status: wersja 0.1.0 (wczesna). Licencja Apache 2.0.
Projekt nieoficjalny. Niezwiązany z Shoper S.A. ani przez nią nie wspierany. „Shoper” to nazwa platformy, do której serwer się łączy, użyta wyłącznie w celu opisu zgodności. Unofficial project, not affiliated with or endorsed by Shoper S.A.
Narzędzia / Tools
Narzędzie | Co robi | Limit |
| Szuka produktów: fragment nazwy, kod, EAN, kategoria główna, producent (AND) | 1-50 na stronę, |
| Szczegóły produktu po ID, opis bez HTML (do 2000 znaków) | 1 rekord |
| Płaska lista kategorii z liczbą produktów i adresem | 1-50 na stronę, |
| Hierarchia kategorii z nazwami, opcjonalnie poddrzewo i głębokość | 1000 węzłów |
| Stany i ceny dla 1-50 produktów, z wariantami | 1-50 wierszy na stronę |
| Producenci (marki), opcjonalnie po fragmencie nazwy | 1-50 na stronę, |
Wszystkie mają adnotację readOnlyHint: true. Odpowiedź zawiera total, page, pages, returned.
Related MCP server: Shopify Storefront MCP Server
Czego serwer celowo NIE robi
Żadnego zapisu. Klient HTTP ma tylko metodę
get(); jedyny POST to pobranie tokenu (/webapi/rest/auth). Test jednostkowy przeszukuje źródła i pada przy PUT/PATCH/DELETE albo dodatkowym POST.Żadnych zamówień, klientów, adresów, płatności, użytkowników. Klient przyjmuje tylko zasoby z listy:
products,product-stocks,categories,categories-tree,producers. Inny zasób kończy się błędem, nawet gdyby narzędzie próbowało go pobrać. Powód: dane osobowe nie trafiają do modelu.Bez ceny zakupu i marży. Pola odpowiedzi są z białej listy;
price_buyingnigdy nie wychodzi.Bez dostępu do plików sklepu, szablonów, ustawień, webhooków.
Bezpieczeństwo
Sekrety tylko w zmiennych środowiskowych. W repo jest
.env.examplebez wartości. Login, hasło i token są maskowane (***) w każdym komunikacie błędu; nagłówkiBearer/Basicteż.Używaj osobnego użytkownika WebAPI z rolą tylko do odczytu (sekcja Konto tylko do odczytu). Serwer przy każdym starcie wypisuje o tym ostrzeżenie na stderr.
Limity wywołań: domyślnie 30 wywołań narzędzi na minutę i 500 na proces (
SHOPER_MCP_MAX_CALLS_PER_MINUTE,SHOPER_MCP_MAX_CALLS_TOTAL). Chroni sklep przed pętlą agenta.Limity API Shopera: serwer czyta nagłówki kubełka (
X-Shop-Api-Calls,X-Shop-Api-Limit,X-Shop-Api-Bandwidth), zwalnia przed zapełnieniem, przy 429 ponawia do 3 razy (zRetry-Afteralbo odstępem wykładniczym). Minimalny odstęp między zapytaniami: 500 ms (SHOPER_MCP_MIN_DELAY_MS, co najmniej 200). Równoległe wywołania narzędzi przechodzą przez jedną kolejkę, a token pobiera jedno wspólne zapytanie.Retry-Afterograniczone do 60 s. Klient HTTP nie podąża za przekierowaniami.Prompt injection w danych produktu. Nazwy i opisy produktów pisze właściciel sklepu albo import z hurtowni. Mogą zawierać tekst udający polecenie („zignoruj instrukcje…”). Serwer:
zdejmuje HTML, skrypty i komentarze (parser liniowy; wejście przycinane przed przetwarzaniem, więc pole o rozmiarze MB nie blokuje serwera);
usuwa znaki sterujące i niewidoczne: bidi, zero-width, selektory wariantów, znaki Unicode Tag (U+E0000–E007F, „ASCII smuggling”);
encje HTML dekoduje raz, przed zdjęciem tagów, więc
<img…>nie wraca jako znacznik;przycina pola (nazwa 300, opis 2000 znaków);
category_pathsicategoriesprzyjmuje wyłącznie jako liczby, z limitem liczby elementów;opakowuje każdą odpowiedź polem
_untrusted_data_notice: to dane, nie polecenia;podaje to samo w instrukcjach serwera MCP. Najważniejsza ochrona to brak narzędzi z zapisem: nawet zmanipulowany agent nie ma czym nic zmienić w sklepie. Jeśli ten sam agent ma inne narzędzia z zapisem (poczta, pliki), traktuj dane ze sklepu jak każdą treść z internetu.
Opcjonalny dziennik zapytań HTTP na stderr:
SHOPER_MCP_AUDIT_LOG=1(metoda i zasób, bez parametrów i nagłówków).
Instalacja
Wymaga Node.js 20+.
git clone <adres-repozytorium> shoper-mcp && cd shoper-mcp
npm ci
npm test # testy jednostkowe, bez sieciKonfiguracja (zob. .env.example): SHOPER_URL (https), SHOPER_LOGIN, SHOPER_PASSWORD użytkownika WebAPI.
Claude Code
claude mcp add --scope local shoper \
-e SHOPER_URL=https://shop.example.com -e SHOPER_LOGIN=... -e SHOPER_PASSWORD=... \
-- node /sciezka/do/shoper-mcp/src/index.jsUwaga: -e zapisuje wartości w ~/.claude.json. Lepiej uruchomić serwer przez własny skrypt, który pobiera hasło z menedżera sekretów i przekazuje je w środowisku procesu.
Konto tylko do odczytu
Serwer nie wykonuje zapisu (patrz wyżej), ale drugą linią obrony są uprawnienia konta w Shoperze. Shoper nie zwraca zakresu tokenu (odpowiedź /webapi/rest/auth zawiera tylko access_token, expires_in, token_type), a jedynym sposobem sprawdzenia prawa zapisu jest próba zapisu. Serwer jej celowo nie robi. Dlatego przy każdym starcie wypisuje ostrzeżenie na stderr.
W panelu administracyjnym Shopera utwórz osobnego użytkownika z dostępem do WebAPI i rolą (uprawnieniami) tylko do odczytu katalogu: produkty, kategorie, producenci, stany.
Podaj jego dane w
SHOPER_LOGIN/SHOPER_PASSWORD. Nie używaj głównego administratora ani konta z prawem zapisu.Sprawdź raz, ręcznie i poza serwerem, że próba zapisu tym kontem kończy się błędem 403 (
insufficient_scope).
Tryb ścisły: SHOPER_REQUIRE_READONLY=1 wstrzymuje start (kod 2), dopóki nie ustawisz SHOPER_READONLY_ACK=1. Kompromis: to deklaracja człowieka po kroku 3, nie weryfikacja przez API. Chroni przed przypadkowym podpięciem konta z zapisem w środowisku, w którym ktoś pamiętał o ustawieniu trybu ścisłego, ale nie potwierdzi uprawnień za ciebie. Ostrzeżenie wypisywane jest także po potwierdzeniu.
Test na żywym sklepie
SHOPER_URL=... SHOPER_LOGIN=... SHOPER_PASSWORD=... npm run test:liveOpcjonalnie SHOPER_MCP_LIVE_QUERY=<fraza> dla wyszukiwania; bez niej test bierze pierwsze produkty. Test wypisuje same liczby, bez rekordów sklepu.
Uruchamia serwer przez prawdziwy protokół MCP (stdio), woła narzędzia, sprawdza limity, brak narzędzia do zamówień i dziennik metod HTTP (tylko GET + POST /auth).
Ograniczenia znane
Shoper nie łączy filtrów przez OR:
search_productsz kilkoma filtrami zwraca ich część wspólną.category_idfiltruje po kategorii głównej produktu, nie po wszystkich przypisanych.Język treści:
SHOPER_LANG(domyślniepl_PL).Limit wywołań (
SHOPER_MCP_MAX_CALLS_PER_MINUTE) liczy wywołania narzędzi, nie zapytania HTTP:category_treeto 1 + do 20 zapytań. Przed przeciążeniem sklepu chroni odstęp między zapytaniami i odczyt kubełka Shopera.429 przy pobieraniu tokenu nie jest ponawiane (kończy wywołanie błędem; kolejne wywołanie spróbuje ponownie).
Limit czasu (
SHOPER_MCP_TIMEOUT_MS) obejmuje oczekiwanie na nagłówki, nie czytanie treści odpowiedzi; brak limitu rozmiaru odpowiedzi. Zakładamy zaufany serwer sklepu po https.Uprawnień konta WebAPI nie da się sprawdzić bez próby zapisu (sekcja „Konto tylko do odczytu”).
Licencja
Apache License 2.0 (LICENSE, NOTICE). Możesz używać, zmieniać i wdrażać, także komercyjnie, bez nas. Licencja daje też wprost prawo do naszych ewentualnych patentów. Zmienione pliki oznacz i zachowaj NOTICE.
Licensed under the Apache License, Version 2.0.
Available Tools
6 toolscategory_treeDrzewo kategorii / Category treeBRead-onlyIdempotent
PL: Hierarchia kategorii z nazwami i liczbą produktów (maks. 1000 węzłów). Opcjonalnie od wybranego węzła i do zadanej głębokości. EN: Category hierarchy with names and product counts, optionally from a given node and up to a depth.
Inputs: root_id, max_depth.
get_productSzczegóły produktu / Get productARead-onlyIdempotent
PL: Zwraca szczegóły jednego produktu po ID: nazwa, kody, ceny, stan, kategorie, producent, opis (oczyszczony z HTML, przycięty). Tylko odczyt. EN: Returns one product by ID (read-only), description stripped of HTML and truncated.
Inputs: product_id (required).
get_stockStany i ceny / Stock and pricesARead-onlyIdempotent
PL: Stany magazynowe i ceny dla 1-50 produktów (także warianty). Bez ceny zakupu. Tylko odczyt. EN: Stock levels and prices for 1-50 products, including variants. No purchase price. Read-only.
Inputs: product_ids (required), page, limit.
list_categoriesLista kategorii / List categoriesARead-onlyIdempotent
PL: Płaska lista kategorii sklepu z liczbą produktów i adresem. Maks. 50 na stronę. Do hierarchii użyj category_tree. EN: Flat, paginated list of categories. Use category_tree for hierarchy.
Inputs: page, limit.
list_producersProducenci / List producersARead-onlyIdempotent
PL: Lista producentów (marek) sklepu, opcjonalnie po fragmencie nazwy. Maks. 50 na stronę. EN: Paginated list of producers (brands), optionally filtered by name fragment.
Inputs: page, limit, query.
search_productsWyszukaj produkty / Search productsARead-onlyIdempotent
PL: Wyszukuje produkty w katalogu sklepu Shoper (tylko odczyt). Filtry łączone przez AND: fragment nazwy, kod, EAN, kategoria główna, producent. Maks. 50 wyników na stronę, paginacja przez "page". Zwraca cenę, stan, aktywność, adres. EN: Searches the Shoper store product catalog (read-only). Filters combined with AND. Paginated, max 50 per page.
Inputs: ean, code, page, limit, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct resource: product search, single product, stock, flat categories, category hierarchy, producers. The only mild overlap is get_product vs get_stock, since both surface price and stock, but descriptions clarify that get_stock is bulk (1-50 products, variants) and get_product is single-item detail. Cross-references (list_categories points to category_tree) further reduce confusion.
Five of six tools follow a clean verb_noun snake_case pattern (search_products, get_product, list_categories, get_stock, list_producers). category_tree breaks the pattern by omitting a verb and using a singular noun, but it remains readable and self-explanatory.
Six tools is a lean but well-scoped set for a read-only catalog-browsing server; each tool earns its place. It sits at the thin end of the ideal 3-15 range, with no filler tools, but also no redundancy to absorb broader use cases.
For a read-only product-catalog surface, coverage is solid: search, detail, stock/variants, flat and hierarchical categories, and producers. Missing only minor conveniences such as product-by-SKU/EAN lookup as a dedicated tool or attribute/dictionary listings; write operations are explicitly out of scope, so this is not a gap.
Maintenance
Related MCP Connectors
Live data for AI agents. Search the catalog, read the price, call the tool; keys stay server-side.
AI-agent product catalog: search, lookup & purchase routing over verified merchant data.
Merchant product catalogs for AI agents: price, availability, specs, variants, buy links. Read-only.
Read-only product catalog for shopping agents: search, details, compatibility, shop answers.
81
Related MCP Servers
AlicenseNot gradedqualityBmaintenanceEnables AI assistants to interact with Saleor Commerce instances to fetch data about products, customers, and orders through a read-only GraphQL API integration. Supports secure authentication and domain validation for connecting to Saleor cloud instances.19AGPL 3.0- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to query and interact with Shopify store data via the Storefront API, including products, collections, carts, and customer information.9-
- AlicenseAqualityCmaintenanceEnables AI agents to read and write Shopify store data including products, orders, customers, inventory, and more via the Admin GraphQL API.2858 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to browse product catalogs, search products with filters, and initiate checkouts, generating order summaries and checkout URLs.-