Magento MCP

Local, read-only TypeScript MCP server for Magento Open Source and Adobe Commerce PaaS/on-premises 2.4.x REST APIs. One process binds one Magento installation, bearer token, and fixed store scope.

Capabilities

• Discover bounded, schema-advertised Magento GET operations.
• Execute exact built-in or reviewed custom route profiles through magento_query.
• Build bounded Magento SearchCriteria without accepting raw bracket query keys.
• Look up exactly one customer by positive ID or exact email plus website ID.
• Resolve product inventory through MSI salable semantics with explicit legacy fallback.
• Enforce GET-only requests, fixed origin/store scope, redirect denial, response limits, JSON limits, PII minimization, and rolling budgets.

No mutations, arbitrary HTTP, direct database access, generic customer enumeration, bulk export, or hidden automatic pagination.

Requirements

• Node.js 22 or newer
• Magento Open Source or Adobe Commerce PaaS/on-premises 2.4.x
• Read-only Magento admin or integration bearer token
• HTTPS Magento base URL, except explicitly enabled loopback development

Magento 2.4.4+ disables standalone integration bearer-token authentication by default. Enable oauth/consumer/enable_integration_as_bearer for a read-only integration token, or use a supported admin bearer token. OAuth 1.0a is outside this release.

Run with npx

No source clone or local build is required:

MAGENTO_BASE_URL="https://magento.example.com" \
MAGENTO_ACCESS_TOKEN="replace-locally-with-read-only-token" \
npx -y [email protected]

The command starts a stdio MCP server and waits for an MCP client. Stdout belongs only to MCP JSON-RPC framing. Safe startup diagnostics use stderr.

Build from source

git clone https://github.com/coffeemugvn/AI-mcps.git
cd AI-mcps
npm ci
npm run typecheck
npm test
npm run build

Built entrypoint:

node dist/src/index.js

Configuration

Required process environment:

| Variable | Meaning | |---|---| | MAGENTO_BASE_URL | Magento installation root, such as https://magento.example.com/; do not include /rest, query, fragment, or credentials | | MAGENTO_ACCESS_TOKEN | Read-only bearer token; never accepted as tool input |

Optional:

| Variable | Default | Meaning | |---|---|---| | MAGENTO_STORE_CODE | all | Fixed REST store scope. all means Magento admin scope, not all-store aggregation | | MAGENTO_WEBSITE_CODE | none | Default website code for MSI stock resolution | | MAGENTO_WEBSITE_ID | none | Default website ID for exact customer email lookup | | MAGENTO_INSTALLATION_LABEL | base URL hostname | Safe installation label returned in tool results | | MAGENTO_ROUTE_PROFILES_FILE | none | Absolute path to version-1 custom profile file | | MAGENTO_ALLOW_INSECURE_LOCALHOST | false | Permit HTTP only for loopback development | | MAGENTO_CATALOG_REVISION | none | Immutable deployment/schema artifact ID; enables persistent normalized catalog reuse only with namespace | | MAGENTO_CATALOG_NAMESPACE | none | Required with revision; non-secret authority-domain identifier separating credential/ACL visibility | | MAGENTO_CATALOG_CACHE_DIR | OS user cache under magento-mcp | Optional absolute local-filesystem cache directory |

Persistent catalog reuse stays disabled unless revision and namespace are both set. Values use [A-Za-z0-9._-], length 1-128. Deployment automation must keep revision stable across restarts and bump it for Magento/core, module, webapi.xml, relevant ACL, fixed-store, emergency restore, and rollback changes. Revision is operator assertion, not proof of remote state; forgotten bumps can preserve stale metadata. Cache mismatch, corruption, symlink, unsafe file, checksum, builder, or format failures trigger authenticated refresh. Failed refresh never executes stale cache. Disable by unsetting revision and namespace, then restart. Delete cache entries only while server is stopped. Cache stores normalized catalog metadata only; no token, token hash, raw schema, headers, URL query, or business data.

Readiness: after deployment revision change or restart, call magento_discover_api once and require success before marking integration healthy. Safe stderr events distinguish disabled, hit, rejection reason, schema refresh duration/bytes, publication, and publication failure. Events never contain cache path, namespace, revision, credentials, or raw schema.

Use .env.example as variable reference. Do not commit real secrets.

One process uses one fixed MAGENTO_STORE_CODE. Start separate MCP processes for separate Magento installations or store scopes.

MCP client configuration

Copy examples/claude-code.mcp.json and provide credentials through local MCP client configuration. Example file contains placeholders only and pins [email protected] for reproducible startup. Update version deliberately when adopting a new release.

Custom route profiles remain local files. Set MAGENTO_ROUTE_PROFILES_FILE to an absolute path for a reviewed profile file; npm package includes examples/custom-route-profiles.json as a reference, not an automatically loaded policy.

Tools

magento_discover_api

Search normalized Magento operation catalog. Permanently denied routes never appear. executableOnly defaults to true, limit defaults to 20 and caps at 100. Result includes schema-only catalogFingerprint and additive capabilityFingerprint.

Call discovery when canonical route or current capability fingerprint is unknown, or after PROFILE_SCHEMA_MISMATCH. Known routes may call magento_query directly with prior capability fingerprint.

magento_query

Execute one exact approved route profile. Inputs:

• canonical routeKey, for example GET /V1/products/{sku}
• optional catalogFingerprint
• declared scalar pathParams and queryParams
• optional bounded SearchCriteria AST

Filters within one group use Magento OR semantics. Separate groups use AND semantics. One call returns one page only.

Order collections require exact entity/increment ID, or strict offset-bearing RFC 3339 created_at lower and upper bounds no wider than 31 days. Customer ID requires the same bounded date range. Invoice, shipment, and credit-memo collections require exact entity/increment/order ID, exact created_at, or a bounded created_at range no wider than 31 days. Dates normalize to Magento UTC second format. Core order-by-item-SKU filtering is not advertised because Magento's standard order repository does not guarantee that join/filter.

magento_get_customer

Exact lookup only:

• customerId, or
• email plus websiteId, where configured MAGENTO_WEBSITE_ID may supply default

Email search uses exactly two server-owned filter groups and page size 2 for ambiguity detection. Search result exposes only ID/email/website ID; server fetches final PII-minimized detail by exact customer ID. Generic customer collection query remains unavailable.

magento_query_inventory

Provide exactly one sku or positive productId; optional websiteCode overrides configured default for this helper only, not REST store scope.

Server resolves exact product, probes MSI source items, resolves website stock, queries salable quantity/status, and includes legacy stock compatibility when available. MSI permission/auth/upstream failures fail closed; only confirmed missing MSI capability permits legacy fallback. Composite caps: six calls, 3 MiB aggregate response bytes, 30 seconds.

Custom route profiles

Runtime Swagger describes compatibility, not authorization. Custom GET execution requires explicit profile in MAGENTO_ROUTE_PROFILES_FILE. See examples/custom-route-profiles.json.

Rules:

• file and profile version must be 1
• exact canonical GET /V1/... route key; no wildcard or operation-ID authorization
• readOnlyConfirmed: true
• custom sensitivity must be non_pii
• declared scalar path/query policies
• optional configured SearchCriteria field/operator limits
• bounded pagination and response bytes
• passthrough or allow_fields response mode
• malformed, duplicate, or conflicting profiles fail startup
• profile/schema/module/store changes require restart
• customer-self and guest-cart route families are permanently denied; custom profiles cannot enable /V1/carts/mine, /V1/guest-carts/..., or /V1/customers/me

Built-in response policies use explicit field projection. Product custom attributes expose only reviewed codes (url_key currently); product media drops custom and extension fields; cart summaries omit customer identity, addresses, payment, notes, and item options.

Least-privilege Magento ACL

Grant only required read resources. Typical capabilities:

• Orders: Magento_Sales::actions_view
• Products: Magento_Catalog::products; media list: Magento_Catalog::catalog; media detail/types: Magento_Catalog::attributes_attributes
• Legacy stock: Magento_Catalog::catalog_inventory
• MSI source items: Magento_InventoryApi::source; stock resolver/salability: Magento_InventorySalesApi::stock
• Customers: Magento_Customer::customer
• Categories: Magento_Catalog::categories
• Customer groups: Magento_Customer::group
• Invoices: Magento_Sales::sales_invoice
• Shipments: Magento_Sales::shipment
• Credit memos: Magento_Sales::sales_creditmemo
• Admin cart summaries: Magento_Cart::manage

Built-in coverage includes bounded GET /V1/categories/list, customer-group search/detail/default routes, and invoice/shipment/credit-memo list/detail routes. Sales collection routes require an exact identifier or bounded 31-day created_at selection. Sales outputs expose reviewed financial, status, and line-item fields while excluding comments, shipment labels/tracks, addresses, customer identifiers, transaction/payment metadata, item cost/additional data, and arbitrary extension/custom attributes. Category tree/detail remains deferred until recursive projection is separately approved.

GET-only server behavior does not compensate for an over-privileged token.

Errors and limits

Expected tool failures return stable safe codes and isError: true. Raw Magento bodies, headers, bearer values, URL query values, payload fragments, stack traces, caller-supplied parameter names/values, and PII are not returned. Generic responses marked sensitive, pii, or high_pii emit host/model-context warnings; exact customer lookup emits a PII warning.

Notable limits:

• business response default 1 MiB, profile hard max 2 MiB
• schema response 5 MiB
• JSON depth 40, nodes 100,000, array items 10,000, string 64 KiB
• request timeout 15 seconds
• process rolling budget: 60 calls, 2,000 returned records, 20 MiB per minute
• no partial JSON on limit failure

Verification

npm ci
npm run typecheck
npm run build
npm test
npm audit --audit-level=moderate

Manual MCP Inspector:

npx @modelcontextprotocol/inspector node /absolute/path/to/magento-mcp/dist/src/index.js

Real Magento smoke testing requires authorized credentials and test installation. Automated suite uses mocked schema/HTTP and real in-memory/stdio MCP transports.

License

Licensed under the Apache License 2.0. You may use, modify, and distribute this software, including for commercial purposes, subject to the license terms.

Magento and Adobe Commerce are trademarks of Adobe. This independent project is not affiliated with or endorsed by Adobe.