magento-mcp

MCP server exposing a Magento 2 store to AI assistants via:

• REST Admin API — catalog, orders, customers, CMS, inventory, promotions, store config (write tools require confirm: true), authenticated via OAuth 1.0a against a Magento Integration
• GraphQL — storefront-shaped catalog search, product details, category tree
• Direct read-only SQL — a run_readonly_sql tool plus prebuilt insight queries against the live Magento database, optionally reached over an SSH tunnel

Tools

Tool	Domain	Notes
search_products, get_product, list_categories	Catalog	read-only
update_product, delete_product	Catalog	destructive, confirm: true required
search_orders, get_order	Orders	read-only
cancel_order, refund_order	Orders	destructive, confirm: true required
search_customers, get_customer	Customers	read-only
update_customer, delete_customer	Customers	destructive, confirm: true required
list_cms_pages, get_cms_page, list_cms_blocks	CMS	read-only
get_stock_item, list_source_items	Inventory	read-only
update_stock_item	Inventory	destructive, confirm: true required
list_cart_price_rules, get_coupon_by_code	Promotions	read-only
get_store_config, list_store_views	Store config	read-only
set_config_value	Store config	destructive, confirm: true required
search_catalog, get_product_details, get_category_tree	GraphQL catalog	read-only, storefront-shaped queries
run_readonly_sql	Database	single SELECT only — see Safety notes
top_selling_products, low_stock_items, abandoned_carts	Database	prebuilt read-only insight queries

Also exposes one MCP resource: magento://store/config (store configuration — currencies, locales, store views, base URLs).

Prerequisites

• Node.js >= 18
• A Magento 2 store (Open Source or Adobe Commerce) with REST/GraphQL enabled
• A Magento Integration for OAuth 1.0a credentials (see Quick Start below) — admin-user password auth is not supported
• MySQL/MariaDB network access to the Magento database, for the read-only SQL tools (optional — the REST/GraphQL tools work without it)

Quick Start (using the published package)

No clone or build needed — this installs and runs on demand via npx.

1. In Magento Admin: System → Extensions → Integrations → Add New Integration. Grant it only the API resources this server actually needs, then Activate it to get four OAuth 1.0a values (shown once): consumer key/secret, access token/secret. This also sidesteps the 2FA restriction that blocks admin-user password auth.

2. If using the DB tools, create a SELECT-only MySQL user:

   CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'change_me';
   GRANT SELECT ON magento_db.* TO 'mcp_readonly'@'%';
   FLUSH PRIVILEGES;
   

   Do not grant this user INSERT/UPDATE/DELETE/DDL under any circumstance — the application-level query guard (src/db/guard.ts) is defense in depth, not the safety boundary.

3. Register with Claude Desktop/Code, e.g. in claude_desktop_config.json:

   {
     "mcpServers": {
       "magento": {
         "command": "npx",
         "args": ["-y", "@fahadhussain777/magento-mcp"],
         "env": {
           "MAGENTO_BASE_URL": "...",
           "MAGENTO_CONSUMER_KEY": "...",
           "MAGENTO_CONSUMER_SECRET": "...",
           "MAGENTO_ACCESS_TOKEN": "...",
           "MAGENTO_ACCESS_TOKEN_SECRET": "...",
           "MAGENTO_DB_HOST": "...",
           "MAGENTO_DB_NAME": "...",
           "MAGENTO_DB_READONLY_USER": "...",
           "MAGENTO_DB_READONLY_PASSWORD": "...",
           "MAGENTO_DB_SSH_HOST": "...",
           "MAGENTO_DB_SSH_USER": "...",
           "MAGENTO_DB_SSH_PRIVATE_KEY_PATH": "..."
         }
       }
     }
   }
   

   The MAGENTO_DB_SSH_* fields are only needed when tunneling the DB connection over SSH — omit them entirely (not just leave blank) to connect directly. See "Reaching a remote/firewalled DB" below.

   If REST calls fail with {"message":"Signature method %1 is not supported","parameters":["HMAC-SHA1"]}, add "MAGENTO_OAUTH_SIGNATURE_METHOD": "HMAC-SHA256" to the env block — Magento instances vary on which OAuth1 signature method they accept (defaults to HMAC-SHA1 if unset). Check Magento Admin under Stores → Configuration → Services → OAuth if unsure which one a given instance requires.

Development (working on this repo)

1. npm install
2. Copy .env.example to .env and fill in the same OAuth/DB values as Quick Start above.
3. npm run build
4. npm run test:connections — sanity-checks REST auth, GraphQL, and the DB connection against the values in .env. See Local dev with self-signed certs below if this fails on TLS.
5. In claude_desktop_config.json, use "command": "node", "args": ["/path/to/magentoMCP/dist/index.js"] instead of the npx form, so you're running your local changes instead of the published version.

Publishing

Published at npmjs.com/package/@fahadhussain777/magento-mcp. To publish a new version:

1. Bump version in package.json (semver) — npm rejects re-publishing an existing version.
2. Make sure you're logged in as the intended npm account: npm whoami (or npm login).
3. npm publish — prepublishOnly (typecheck + test + build) runs automatically first and aborts the publish if any of them fail. The package is scoped with publishConfig.access: "public" already set, so this publishes publicly on the free tier without needing --access public on the command line.

To test a packed tarball locally without touching the registry: npm pack, then npm install /path/to/the/tarball.tgz in a scratch project.

Development scripts

• npm run dev — run directly from TS source via tsx
• npm run typecheck
• npm test — unit tests (src/db/guard.test.ts covers the SQL safety guardrails)
• npm run test:connections — live smoke test of REST/GraphQL/DB reachability against .env (not a substitute for npm test)
• npx @modelcontextprotocol/inspector node dist/index.js — interactively list/invoke tools

Local dev with self-signed certs (mkcert, Warden, etc.)

Node's fetch uses its own bundled CA list, separate from your system's trust store — so even if curl and your browser trust a locally-issued mkcert certificate, Node will reject it with UNABLE_TO_VERIFY_LEAF_SIGNATURE. Point Node at the same root CA:

NODE_EXTRA_CA_CERTS=$(mkcert -CAROOT)/rootCA.pem npm run dev

or set NODE_EXTRA_CA_CERTS in the environment your MCP client launches the server with (e.g. the env block in claude_desktop_config.json). Also double-check MAGENTO_BASE_URL actually matches a hostname the certificate covers (ERR_TLS_CERT_ALTNAME_INVALID means it doesn't) — local Magento setups often have several *.local/*.example.com hostnames configured and only one has a matching cert.

Docker-based setups (e.g. Warden, markoshust/magento-docker): the container itself may generate its own mkcert CA independently of your host's mkcert -CAROOT — if so, the CA cert lives inside the container, not on the host, and gets regenerated (new CA, still UNABLE_TO_VERIFY_LEAF_SIGNATURE even with a previously-working NODE_EXTRA_CA_CERTS path) whenever the container is recreated. Pull the current one out with:

docker exec <nginx-container> find / -iname '*mkcert*.crt' 2>/dev/null
docker cp <nginx-container>:<path-from-above> ./magento-dev-ca.pem

then point NODE_EXTRA_CA_CERTS at that file. Also worth checking after any container restart: docker inspect <db-container> --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' — container IPs on the Docker bridge network can change across restarts, so a previously-working MAGENTO_DB_HOST may go stale (ECONNREFUSED) even though nothing in .env looks wrong.

Reaching a remote/firewalled DB (SSH tunnel)

MAGENTO_DB_HOST/PORT don't need to be on the same machine as this server — mysql2 just connects over TCP. But never expose MySQL's port to the open internet to make that work. If the DB isn't already reachable over a private network/VPN, set MAGENTO_DB_SSH_* in .env (see .env.example for the full field list) to tunnel the DB connection through SSH instead — this server opens the SSH connection itself (via the ssh2 package, not a shelled-out ssh process) and forwards a local port to MAGENTO_DB_HOST/PORT as resolved from the SSH host's side. A private key (MAGENTO_DB_SSH_PRIVATE_KEY_PATH) is preferred over a password. Leave MAGENTO_DB_SSH_HOST unset to connect directly, as before — the tunnel is opt-in and only engages when that variable is present.

Safety notes

• Every destructive REST tool (update_product, delete_product, cancel_order, refund_order, update_customer, delete_customer, update_stock_item, set_config_value) previews the action and no-ops unless called with confirm: true.
• run_readonly_sql only accepts a single SELECT statement, rejects DML/DDL keywords and sensitive tables (admin_user, etc.), and injects/caps a LIMIT — see src/db/guard.ts. This is on top of, not instead of, the DB user's SELECT-only grants.
• Query timeout and row cap are configurable via MAGENTO_DB_QUERY_TIMEOUT_MS / MAGENTO_DB_MAX_ROWS in .env.

Issues & contributing

Bugs and feature requests: github.com/FahadEjaz/magento-mcp/issues. MIT licensed — see LICENSE.