mage-os-mcp
This server lets an AI agent shop and query a Magento/Mage-OS store over MCP through its storefront GraphQL API.
Search & discover: free-text product search with pagination/sorting; browse the category tree and list products in a category by uid.
Product detail & stock: fetch full product details (descriptions, pricing/discounts, categories, images) and batch-check stock for up to 100 SKUs.
Shopping cart: create guest carts, add items by SKU/quantity (with per-item errors surfaced), and view cart contents/totals.
Customer account: log in as a customer, view the profile and saved addresses, and look up order status, totals, items, and tracking.
Checkout flow: set guest email and shipping address, choose a shipping method, set a payment method, and place the order.
B2B (optional): retrieve an authenticated customer's company/team and requisition lists when the store exposes B2B GraphQL data.
Safety & governance: audited tool calls, self-describing prices (tax mode, tier pricing), and revocable sessions.
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., "@mage-os-mcp Find me a waterproof jacket under $100 and tell me if it's in 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.
mage-os-mcp
An open-source Model Context Protocol (MCP) server that lets AI agents shop and query a Magento / Mage-OS store. It connects to a store's public storefront GraphQL API, so any Magento 2.4+ / Mage-OS store can use it — no module to install, no admin credentials required for the core catalog tools.
Mage-OS B2B initiative: this server is a reuse candidate for the community B2B suite's MCP adapter.
docs/b2b-reuse-review.md— adopt / adapt / replace review of this server.
docs/b2b-mcp-requirements.md— the RFC's MCP requirements mapped to progress.
docs/b2b-auth-model.md— entities, ER diagram and the operation state machine.
docs/b2b-community-feedback.md— RFC discussion feedback and what it changes here.Work in progress lives on the
b2b-delegated-authbranch (src/auth/).
Point Claude (or any MCP client) at your store and ask: "Find me a waterproof jacket under $100 and tell me if it's in stock."
Why another Magento MCP?
Most existing Magento MCP servers are either developer tooling (help you write Magento code), admin/BI dashboards (REST + admin token), or coupled to a commercial SaaS. mage-os-mcp is deliberately different:
Shopper-first. A small, curated, read-first toolset focused on the "let an AI agent shop" use case — quality over surface area.
API-based & portable. Talks to the storefront GraphQL endpoint. Works against any store, self-hosted or cloud. No Magento module to deploy.
GraphQL-first. Uses the storefront GraphQL API where practical; REST/direct only where GraphQL genuinely can't do it.
Truly open — MIT licensed. Fork it, ship it, build on it.
Related MCP server: Shopify Storefront MCP Server
Status
Early v1. Working tools:
Tool | Description | API |
| Free-text catalog search → SKU, name, price, stock, image | GraphQL |
| Full product detail by SKU → description, pricing, discounts, stock, categories, media | GraphQL |
| Batch availability check for up to 100 SKUs → in-stock flag + low-stock qty | GraphQL |
| Store category tree (departments + subcategories) with product counts | GraphQL |
| List products in a category by | GraphQL |
| Start an anonymous shopping cart → returns a | GraphQL |
| Add products (SKU + quantity) to a guest cart; per-item errors surfaced | GraphQL |
| View a guest cart's line items and totals by | GraphQL |
| Authenticate a customer (email + password) → returns a | GraphQL |
| Revoke a | — |
| Logged-in customer's profile & saved addresses (by | GraphQL |
| Logged-in customer's orders — status, totals, items, tracking | GraphQL |
| Checkout step 1: set guest email + address → available shipping methods | GraphQL |
| Checkout step 2: pick a shipping method → available payment methods + totals | GraphQL |
| Checkout step 3: pick a payment method → confirm totals | GraphQL |
| Checkout final step: submit the cart → returns the order number | GraphQL |
| Authenticated customer's B2B company + team roster (optional) | GraphQL |
| Authenticated customer's B2B requisition lists + items (optional) | GraphQL |
Note on B2B:
get_my_companyandget_requisition_listsrequire the store to expose B2B data over GraphQL — the open-source Orangecat B2B suite plus the companion modules (Orangecat_CompanyGraphQl,Orangecat_ProductListsGraphQl). On stores without them, the tools returnsupported: falseinstead of erroring, so they stay safe to include against any store.
Prices are self-describing. Every monetary value is returned as an envelope —
{ amount, currency, tax_mode, price_view, catalog_id, location_id }— not a bare number. A storefront renders prices for a human who can see the context; an MCP client can't, and an agent handed49.99will repeat it as fact and be wrong for whichever audience sees the other tax treatment. Declare your store's treatment withMAGENTO_TAX_MODE=incl|excl; left unset we report"unknown"rather than guess. Catalog reads also surface quantity price breaks (tier_pricing) from nativeprice_tiers— quoting a unit price without knowing 100+ drops it 30% is misleading, not merely incomplete.
Sessions:
loginreturns an opaquesession_id; the underlying credential is held server-side and never returned. Sessions carry a scoped context with expiry and can be revoked (logout) — see the delegated-access model indocs/b2b-auth-model.md.
Governance & audit: every tool call is audited — a redacted, append-only record of who / what / outcome / timing — via a pluggable sink (
MCP_AUDIT,MCP_AUDIT_CHAINfor tamper-evidence). This is the access-control + audit-trail foundation for adopting an MCP under SOC 2-style compliance. Seesrc/governance/.
End-to-end shopping flow
The tools compose into a complete "AI shops the store" journey:
search_products / browse_categories → discover
get_product / check_stock → evaluate
create_guest_cart → add_to_cart → build a basket
set_shipping_address → (returns shipping options)
set_shipping_method → (returns payment options + totals)
set_payment_method → place_order → order number 🎉Note on checkout: the flow uses Magento's guest checkout mutations.
place_orderis irreversible — an agent should confirm the totals with the user first (the tool description instructs it to). Offline payment methods (e.g.checkmo, Check / Money Order) work out of the box; online gateways that need client-side tokenization are out of scope.
Note on carts: the cart tools use Magento's guest cart mutations (no login required).
add_to_cartcurrently targets simple products by SKU; configurable/bundle products (which need selected options) are reported back inuser_errorsand are a planned enhancement.
Note on authentication:
loginexchanges credentials for a Magento customer token viagenerateCustomerToken. The token is stored server-side (in memory) and never returned to the client — tools take an opaquesession_idinstead, so the raw credential stays out of the model's context. Sessions live for the server process lifetime; if it restarts, log in again.
Requirements
Node.js >= 20
A reachable Magento 2.4+ / Mage-OS store with the storefront GraphQL endpoint enabled (the default)
Setup
git clone https://github.com/<you>/mage-os-mcp.git
cd mage-os-mcp
npm install
cp .env.example .env # then edit .env
npm run buildConfiguration
Configuration is via environment variables (see .env.example):
Variable | Required | Default | Description |
| ✅ | — | Store base URL, no trailing |
|
| Store view code, sent as the | |
|
|
| |
|
| Per-request timeout in milliseconds |
Running
# Development (no build step, via tsx)
npm run dev
# Production
npm run build && npm startThe server speaks MCP over stdio. stdout is reserved for the protocol; logs go to stderr.
Try it with the MCP Inspector
npm run inspectTesting
Unit tests (Vitest) run each tool against a mocked GraphQL client, so they need no live store:
npm test # builds, then runs the suite once
npm run test:watchCI (GitHub Actions) type-checks, builds, and tests on Node 20 & 22 for every
push and pull request — see .github/workflows/ci.yml.
Use with Claude Desktop / Claude Code
Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):
{
"mcpServers": {
"mage-os": {
"command": "node",
"args": ["/absolute/path/to/mage-os-mcp/dist/index.js"],
"env": {
"MAGENTO_BASE_URL": "https://app.mage-os.test",
"MAGENTO_INSECURE_TLS": "true"
}
}
}
}Architecture
src/
├── index.ts # MCP server: registers tools, wires stdio transport
├── config.ts # env-based config loader
├── magento/
│ ├── client.ts # GraphQL client (Store header, TLS/timeout handling)
│ └── queries.ts # GraphQL documents (one place to review what we ask for)
└── tools/
├── searchProducts.ts # search_products
└── getProduct.ts # get_productEach tool is a small, testable function that takes the GraphQL client + validated args and returns a plain JSON object. index.ts handles MCP registration and serialization. Adding a tool = one file in tools/ + one query in queries.ts + one registerTool call.
License
MIT — see LICENSE.
Available Tools
11 toolsadd_to_cartAdd to cartA
Add one or more products (by SKU and quantity) to a guest cart. Returns the updated cart with line items and totals. Per-item problems (out of stock, unknown SKU, configurable products needing options) are reported in user_errors rather than failing the whole call.
Inputs: items (required), cart_id (required).
browse_categoriesBrowse categoriesA
Return the store's category tree (departments and their subcategories) with product counts. Use this to discover how the catalog is organized, then pass a category uid to get_category_products to list its items.
Inputs: no named parameters.
check_stockCheck stockA
Check availability for one or more products by SKU. Returns, per SKU, whether it was found, whether it is in stock, and the remaining quantity when the store exposes a low-stock threshold. Use this to confirm availability before recommending or ordering items.
Inputs: skus (required).
create_guest_cartCreate guest cartA
Start a new anonymous (guest) shopping cart. Returns a cart_id that you must pass to add_to_cart and view_cart. Call this once at the start of a shopping session.
Inputs: no named parameters.
get_category_productsGet category productsA
List products within a category by its uid (from browse_categories), with pagination and sorting. Use this to show what's available in a department, e.g. everything in 'Bags'.
Inputs: category_uid (required), sort, pageSize, currentPage.
get_customerGet customer profileA
Get the logged-in customer's profile (name, email, saved addresses) using a session_id from login.
Inputs: session_id (required).
get_order_statusGet order statusA
Look up the logged-in customer's orders (status, date, totals, line items, tracking) using a session_id from login. Optionally pass an order_number to fetch a single order; otherwise the most recent orders are returned.
Inputs: session_id (required), pageSize, order_number.
get_productGet product detailsA
Fetch full details for a single product by its exact SKU: description, pricing (incl. discounts), stock, categories and images.
Inputs: sku (required).
loginLog in (customer)A
Authenticate a customer with email and password. Returns a session_id to use with get_customer and get_order_status. The credential is stored server-side and never returned. Returns success:false with a reason if the credentials are wrong.
Inputs: email (required), password (required).
search_productsSearch productsA
Search the store catalog by free-text term. Returns matching products with SKU, name, price, stock status and image. Use this to discover products before fetching full details with get_product.
Inputs: search (required), sort, pageSize, currentPage.
view_cartView cartA
View the current contents and totals of a guest cart by its cart_id.
Inputs: cart_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Every tool targets a distinct resource and action: catalog search vs. category browsing, product detail vs. stock check, and cart creation vs. cart viewing are clearly separated. Customer tools (login, get_customer, get_order_status) are also unambiguous in their scope.
The vast majority of tools follow a consistent verb_noun snake_case pattern (search_products, get_product, check_stock, add_to_cart, view_cart). The only deviation is 'login', which is a bare verb without an object, but this is a common and acceptable exception.
With 11 tools, the server is well-scoped for a storefront assistant. Each tool covers a meaningful step in catalog browsing, cart management, or customer account access without redundancy or bloat.
The catalog and customer account surfaces are well covered, but the cart workflow is incomplete: there is no way to update quantities or remove items, and there is no checkout or order placement tool. This creates a notable dead end after building a cart.
Maintenance
Related MCP Connectors
Live product search for AI agents across Shopify merchants and major retailers.
AI shopping gateway for product search, inventory, carts, and merchant-hosted checkout.
AI-powered commerce API for luxury skincare shopping. Enables AI agents to search products, browse collections, manage shopping carts, and generate checkout URLs for the Regenique Elegance Shopify store.
Connect AI assistants to your Webanto workspace to review products and copy proposals, explore SEO and imported Search Console opportunities, and search organization knowledge. Inspect workspace capabilities, connection health, usage, and supported operations. Access requires OAuth or a scoped Webanto API key and follows the authorized organization, permissions, and scopes. With separate consent for the applicable paid AI operation, create a product copy proposal and track its job for review; this workflow does not publish changes to your store. A Webanto account and the relevant connected services or uploaded knowledge are required. Paid AI operations require the applicable subscription and available credits. Authentication is required for MCP discovery; an anonymous HTTP 401 is an access challenge, not evidence of a service outage. Official connector repository: https://github.com/empline/webanto-mcp. Support: support@webanto.com.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to manage Adobe Commerce and Magento 2 instances through business-level tools for catalog, promotions, CMS, and SEO. It features secure OAuth 1.0 authentication, safety guardrails for bulk operations, and built-in diagnostic reports for store health.382MIT
- 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
- AlicenseNot gradedqualityDmaintenanceEnables natural language queries about Magento store catalog, sales, and customer data through dynamic tools for AI assistants.MIT