# Magento MCP Server
An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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](https://experienceleague.adobe.com/docs/commerce-admin/systems/integrations.html) configured in Magento with appropriate API permissions
### Installation
```bash
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):
```json
{
"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):
```json
{
"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:
```json
{
"env": {
"FASTLY_SERVICE_ID": "your_service_id",
"FASTLY_API_TOKEN": "your_api_token"
}
}
```
## License
MIT
