Magento MCP Server

An MCP (Model Context Protocol) server for Adobe Commerce / Magento 2 administration. Connects AI assistants like Claude, Windsurf, Cursor, and other MCP-compatible clients to your Magento instance for business-level operations — catalog management, promotions, CMS, diagnostics, and more.

Features

• 30+ tools for Magento administration via the standard MCP protocol
• OAuth 1.0 (HMAC-SHA256) integration authentication — no 2FA prompts
• Two-phase commit for bulk operations (prepare → review → commit)
• Built-in guardrails — bulk caps, price change warnings, confirmation requirements
• Multi-store aware — explicit scope handling for websites, stores, and store views
• Audit logging — every action logged with timestamps, user, and parameters

Available Tools

Auth & Scope

• auth.login / auth.logout / auth.whoami — session management
• scope.list_websites_stores / scope.set_default — multi-store scope

Catalog

• catalog.search_products — search with filters, pagination, field projection
• catalog.get_product — full product details by SKU
• catalog.prepare_bulk_update / catalog.commit_bulk_update — two-phase bulk product updates

Pricing

• pricing.prepare_bulk_price_update / pricing.commit_bulk_price_update — safe bulk price changes with threshold warnings

Promotions

• promotions.search_rules / promotions.get_rule — find and inspect cart price rules
• promotions.prepare_cart_price_rule_create / promotions.commit_cart_price_rule_create — create rules safely
• promotions.update_rule / promotions.enable_rule / promotions.disable_rule
• promotions.generate_coupons / promotions.export_coupons

CMS

• cms.search_pages / cms.get_page — find and read CMS pages
• cms.prepare_bulk_update_pages / cms.commit_bulk_update_pages
• cms.search_blocks / cms.get_block
• cms.prepare_bulk_update_blocks / cms.commit_bulk_update_blocks

SEO

• seo.prepare_bulk_update_url_keys / seo.commit_bulk_update_url_keys — URL key changes with collision detection
• seo.bulk_update_meta — bulk meta title/description/keyword updates
• seo.report_redirect_chains — find redirect chain issues

Diagnostics

• diagnostics.product_display_check — why isn't my product showing?
• diagnostics.indexer_status_report — indexer health check
• diagnostics.inventory_salable_report — MSI stock/salable quantity

Cache

• cache.purge_by_url / cache.purge_product / cache.purge_category — targeted cache invalidation (Fastly or fallback)

Quick Start

Prerequisites

• Node.js 18+
• A Magento 2 / Adobe Commerce instance
• An Integration configured in Magento with appropriate API permissions

Installation

git clone https://github.com/thomastx05/magento-mcp.git
cd magento-mcp
npm install
npm run build

Magento Integration Setup

1. In Magento Admin, go to System > Integrations > Add New Integration
2. Give it a name (e.g., "MCP Server")
3. Under API, select the resources you want to expose
4. Save and Activate the integration
5. Copy the four OAuth credentials:
   • Consumer Key
   • Consumer Secret
   • Access Token
   • Access Token Secret

MCP Client Configuration

Add to your MCP client config (e.g., mcp_config.json for Windsurf, claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "magento-mcp": {
      "command": "node",
      "args": ["C:/path/to/magento-mcp/dist/index.js"],
      "env": {
        "MAGENTO_BASE_URL": "https://your-magento-instance.com",
        "MAGENTO_OAUTH_CONSUMER_KEY": "your_consumer_key",
        "MAGENTO_OAUTH_CONSUMER_SECRET": "your_consumer_secret",
        "MAGENTO_OAUTH_TOKEN": "your_access_token",
        "MAGENTO_OAUTH_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

Alternative: Username/Password Auth

If you prefer admin token auth instead of OAuth (requires handling 2FA if enabled):

{
  "env": {
    "MAGENTO_BASE_URL": "https://your-magento-instance.com",
    "MAGENTO_ADMIN_USERNAME": "your_admin_user",
    "MAGENTO_ADMIN_PASSWORD": "your_admin_password"
  }
}

Usage

Once configured, call auth.login first to establish a session, then use any tool:

> auth.login
Login successful (OAuth 1.0 integration)

> catalog.search_products { filters: { name: { value: "%eye drops%", condition: "like" } } }
Found 12 products...

> diagnostics.inventory_salable_report { sku: "PROD-001" }
Qty: 3,805 | In Stock: Yes | Backorders: Enabled

Architecture

src/
  index.ts              # MCP server entry point (McpServer + StdioServerTransport)
  config/index.ts       # Configuration & guardrail defaults
  actions/              # Tool handlers (one file per domain)
    auth.ts
    catalog.ts
    pricing.ts
    promotions.ts
    cms.ts
    seo.ts
    diagnostics.ts
    cache.ts
    scope.ts
  client/
    magentoRest.ts      # REST client with OAuth 1.0 signing
    fastlyClient.ts     # Optional Fastly CDN integration
  session/
    sessionStore.ts     # In-memory session & OAuth credential storage
    planStore.ts        # Two-phase commit plan storage
    idempotencyLedger.ts
  validation/
    schemas.ts          # Zod input schemas for all tools
    guardrails.ts       # Safety checks (bulk caps, price thresholds, confirmations)
  protocol/
    types.ts            # TypeScript interfaces
  audit/
    auditLogger.ts      # Action audit trail (JSONL)

Security

• No credentials stored on disk — OAuth tokens are passed via environment variables and kept in memory only
• Magento ACL enforced — the integration's API permissions control what the server can do
• Guardrails on top — bulk operation caps, price change thresholds, and confirmation requirements provide defense-in-depth
• Two-phase commit — destructive bulk operations require explicit review and confirmation
• Audit trail — every action is logged with timestamp, user, parameters, and result

Configuration

Guardrails and limits are configurable in src/config/index.ts:

Setting	Default	Description
maxSkusPerBulkCommit	500	Max products per bulk update
maxCouponQtyPerGeneration	1000	Max coupons per generation
priceChangeThresholdPercent	50	Warning threshold for price changes (%)
maxDiscountPercent	50	Max percent discount without override
allowedCatalogUpdateFields	name, description, status, visibility, ...	Whitelist for bulk catalog updates

Optional: Fastly CDN Integration

For targeted cache purge via Fastly, add these environment variables:

{
  "env": {
    "FASTLY_SERVICE_ID": "your_service_id",
    "FASTLY_API_TOKEN": "your_api_token"
  }
}

License

MIT