Elastic Path Composable Commerce MCP Server

Connect your AI assistant to Elastic Path Composable Commerce with comprehensive access to your entire e-commerce platform. This server provides 97 tools across 9 core services including order management, product catalog, catalog views, pricing, promotions, currencies, custom data extensions, cart operations, and advanced analytics through the Model Context Protocol.

What You Get

• Complete Commerce Platform: 97 tools across 9 services - orders, products, catalog views, pricing, promotions, currencies, data extensions, carts, and analytics
• Product Management: Full PIM capabilities with hierarchies, attributes, and catalog management
• Catalog Views: Storefront-ready product browsing with published catalogs, categories, and search
• Pricing Control: Pricebooks, modifiers, volume pricing, and currency management
• Marketing Tools: Promotion creation, rule management, and campaign tracking
• Custom Extensions: Create custom APIs, fields, and data structures for your unique needs
• Advanced Analytics: Deep insights into sales performance, trends, and customer behavior
• Real-time Operations: Direct access to live EPCC data and operations across all services
• Secure Access: Your EPCC credentials stay private and are never shared
• Easy Setup: Configure once, access everything

Quick Setup

Installation

Option 1: NPX (Recommended - No Install)

Add to your MCP client configuration (configuration location and format may vary by client):

{
  "mcpServers": {
    "epcc-commerce": {
      "command": "npx",
      "args": ["-y", "@elasticpath/elasticpath-mcp"],
      "env": {
        "EPCC_CLIENT_ID": "your-epcc-client-id",
        "EPCC_CLIENT_SECRET": "your-epcc-client-secret",
        "EPCC_BASE_URL": "https://useast.api.elasticpath.com"
      }
    }
  }
}

To upgrade: The latest version will be automatically fetched on restart of your MCP client. To use a specific version, add @version to the package name (e.g., @elasticpath/[email protected]).

Option 2: Global Install

Install the package globally:

npm install -g @elasticpath/elasticpath-mcp

Add to your MCP client configuration:

{
  "mcpServers": {
    "epcc-commerce": {
      "command": "elasticpath-mcp",
      "env": {
        "EPCC_CLIENT_ID": "your-epcc-client-id",
        "EPCC_CLIENT_SECRET": "your-epcc-client-secret",
        "EPCC_BASE_URL": "https://useast.api.elasticpath.com"
      }
    }
  }
}

To upgrade: Run npm install -g @elasticpath/elasticpath-mcp@<version> with the desired version and restart your MCP client.

Option 3: From Source

For development or customization:

git clone <repository-url>
cd elasticpath-mcp
npm install
npm run build

Add to your MCP client configuration:

{
  "mcpServers": {
    "epcc-commerce": {
      "command": "node",
      "args": ["/absolute/path/to/elasticpath-mcp/dist/src/local.js"],
      "env": {
        "EPCC_CLIENT_ID": "your-epcc-client-id",
        "EPCC_CLIENT_SECRET": "your-epcc-client-secret",
        "EPCC_BASE_URL": "https://useast.api.elasticpath.com"
      }
    }
  }
}

Get Your EPCC Credentials

You'll need your EPCC application credentials:

• Client ID: Found in your EPCC application settings
• Client Secret: The secret key for your EPCC application

Test It Out

Restart your MCP client and try asking:

• "Show me order metrics for the last 30 days in USD"
• "Get me the details for order ABC123"
• "Show me all products in the Electronics hierarchy"
• "Create a 15% discount promotion for Black Friday"
• "What's the current USD to EUR exchange rate?"
• "Create a custom API for product reviews"

What You Can Ask

Order Management

Get order details, create new orders, and track order status:

Get details for order 12345
Show me all orders from last week
Create a new order for customer abc123

Cart Operations

Manage shopping carts throughout the customer journey:

Create a new cart named "Holiday Shopping"
Add 3 units of product XYZ to cart ABC
Apply promotion code "SAVE20" to cart ABC
Show me all active carts
Checkout cart 789 with customer details

Product Management (PIM)

Comprehensive product catalog and hierarchy management:

Get product details for SKU ABC123
Create a new product in the Electronics category
Show me all products in the Clothing hierarchy
Update product attributes and descriptions
Get all PIM job statuses

Catalog View (Storefront)

Browse published catalogs with customer-facing pricing and navigation:

Show me all published catalogs
Get products from the main storefront catalog
Search for "smartphone" in the electronics catalog
Show me the Electronics category and its subcategories
Get all products in the Clothing/Shirts category
Show me the breadcrumb path for product ABC123

Pricing & Pricebooks

Advanced pricing strategies and volume discounts:

Show me all pricebooks and their product counts  
Create a volume pricing tier for bulk orders
Add price modifiers for seasonal discounts
Get current pricing for product SKU-789

Promotions & Marketing

Campaign creation and rule management:

Get all active promotions
Create a 10% off promotion for category Electronics
Update promotion rules and conditions
Show promotion performance metrics

Currency Management

Multi-currency support and exchange rates:

List all available currencies
What's the current USD to EUR exchange rate?
Update exchange rates for GBP
Create a new currency configuration

Custom APIs

Custom APIs and flexible data structures:

Create a custom API for product reviews
Add rating and comment fields to reviews API
Show all custom APIs in the system
Create a customer loyalty points system

Payment & Transaction Processing

Handle payments, refunds, and transaction tracking:

Show all transactions for order 12345
Refund $50 from transaction TX789
Show payment status for order ABC

Sales Analytics

Get comprehensive metrics and insights:

Show me order summary for Q1 2024 in USD
Show daily order counts for the last 2 weeks
Show hourly revenue trends for Black Friday in USD
Show weekly discount amounts for December in EUR

Available Tools

🛒 Order & Cart Management (14+ tools)

• get_orders - List orders with filtering, pagination, and sorting
• get_order - Get detailed information about a specific order
• create_order - Create new orders with customer and shipping details
• get_carts - List all carts with optional includes
• get_cart - Get detailed cart information including items
• create_cart - Create new shopping carts
• add_to_cart - Add products to existing carts
• apply_promotion_code - Apply Rule Promotion codes to carts
• remove_promotion_code - Remove promotions from carts by item ID
• checkout_cart - Convert carts to orders with customer details
• get_order_transactions - View all transactions for an order
• refund_payment - Process full or partial refunds

📊 Analytics & Data Warehouse (4 tools)

• get_order_metrics_summary - Complete overview of order performance
• get_order_count_timeseries - Track order volume over time
• get_order_value_timeseries - Monitor sales revenue trends
• get_order_discount_timeseries - Analyze discount patterns and impact

Important Notes for Analytics:

• All timestamps are in UTC timezone
• Monetary values are returned in smallest currency subunits (cents for USD/CAD, pence for GBP, etc.)
• The server automatically converts values for display (e.g., 155860 subunits = CAD 1,558.60)

📦 Product Information Management - PIM (15+ tools)

• get_pim_products - List products with comprehensive filtering and includes
• get_pim_product - Get detailed product information with relationships
• create_pim_product - Create new products with attributes and hierarchies
• update_pim_product - Update existing product details and relationships
• delete_pim_product - Remove products from catalog
• get_pim_jobs - Monitor PIM processing jobs and status
• get_pim_job - Get detailed information about specific PIM jobs
• get_pim_job_errors - Retrieve error details for failed PIM operations
• get_hierarchies - List product hierarchies and category structures
• create_hierarchy - Create new category hierarchies
• get_nodes - Get hierarchy nodes and their relationships
• create_node - Add new nodes to existing hierarchies
• get_products_in_node - Find all products within a hierarchy node

🛍️ Catalog View (16 tools)

Storefront-ready access to published catalogs with customer-facing pricing and availability:

• get_catalog_view_catalogs - List published catalogs available for storefront
• get_catalog_view_catalog - Get specific published catalog details
• get_catalog_view_products - Browse products with storefront pricing and stock status
• get_catalog_view_product - Get detailed product view with sale prices and availability
• get_catalog_view_product_by_slug - Access products by SEO-friendly URL slugs
• search_catalog_view_products - Advanced product search with filtering and sorting
• get_catalog_view_hierarchies - List category structures in published catalogs
• get_catalog_view_hierarchy - Get specific category hierarchy details
• get_catalog_view_nodes - Browse category nodes with breadcrumb navigation
• get_catalog_view_node - Get detailed category information
• get_catalog_view_node_by_slug - Access categories by SEO-friendly URL slugs
• get_catalog_view_node_products - List products within specific categories
• get_catalog_view_root_nodes - Get top-level categories for navigation
• get_catalog_view_child_nodes - Get subcategories for hierarchical browsing
• get_catalog_view_product_breadcrumbs - Get navigation path for products
• get_catalog_view_node_breadcrumbs - Get navigation path for categories

💲 Pricebooks & Pricing (12 tools)

• get_pricebooks - List all pricebooks with filtering options
• get_pricebook - Get detailed pricebook information
• create_pricebook - Create new pricebooks for different markets
• update_pricebook - Modify pricebook settings and metadata
• delete_pricebook - Remove pricebooks from system
• replicate_pricebook - Duplicate existing pricebooks with new names
• get_product_prices - List product pricing with currency and tier support
• get_product_price - Get specific product pricing details
• create_product_price - Set product prices with volume tiers
• update_product_price - Modify existing product pricing
• delete_product_price - Remove product price entries
• get_price_modifiers - List pricing modifiers and adjustments
• get_price_modifier - Get specific modifier details
• create_price_modifier - Create percentage or fixed amount modifiers
• update_price_modifier - Update existing pricing modifiers
• delete_price_modifier - Remove pricing modifiers

🎯 Promotions & Marketing (4 tools)

• get_rule_promotions - List active and scheduled promotions
• get_rule_promotion - Get detailed promotion rules and conditions
• create_rule_promotion - Create new promotional campaigns with rules
• update_rule_promotion - Modify existing promotion parameters

💰 Currency Management (6 tools)

• get_currencies - List all configured currencies
• get_currency - Get specific currency details and rates
• get_currency_by_code - Look up currency by ISO code
• create_currency - Add new currency configurations
• update_currency - Modify currency settings and exchange rates
• delete_currency - Remove currency configurations

🔧 Custom APIs (16 tools)

Custom APIs (5 tools):

• get_custom_apis - List all custom API definitions
• get_custom_api - Get specific custom API details
• create_custom_api - Create new extensible API structures
• update_custom_api - Modify custom API configurations
• delete_custom_api - Remove custom APIs

Custom Fields (5 tools):

• get_custom_fields - List fields for a custom API
• get_custom_field - Get specific field definitions
• create_custom_field - Add new fields with validation rules
• update_custom_field - Modify field schemas and constraints
• delete_custom_field - Remove fields from custom APIs

Custom Entries (5 tools):

• get_custom_api_entries - List data entries with filtering
• get_custom_api_entry - Get specific entry details
• create_custom_api_entry - Create new data entries
• update_custom_api_entry - Update existing entry data
• delete_custom_api_entry - Remove data entries

Slug Access (1 tool):

• get_entries_by_slug - Access entries via friendly slug URLs

Configuration Details

Required Settings

| Setting | Description | Example | |---------|-------------|---------| | EPCC_CLIENT_ID | Your EPCC application client ID | abc123def456 | | EPCC_CLIENT_SECRET | Your EPCC application secret | secret_xyz789 | | EPCC_BASE_URL | Your EPCC API endpoint | https://useast.api.elasticpath.com |

Configuration Methods

MCP Client Configuration (Recommended) Your MCP client handles all environment setup. Add the credentials to your client's configuration file as shown in the Installation section above. Most MCP clients follow a similar JSON configuration format.

Local Development Only If you're developing or testing the server directly (outside of an MCP client), create a .env file:

cp .env.example .env
# Edit .env with your credentials

How It Works

1. Authentication: The server automatically authenticates with EPCC using your credentials
2. Token Management: Access tokens are refreshed automatically as needed
3. Query Processing: Your questions are converted to EPCC Data Warehouse API calls
4. Data Formatting: Results are formatted for easy reading

Troubleshooting

Tools don't appear in my client

• Check that your MCP client configuration is valid JSON
• Verify the path to dist/src/local.js is correct
• Make sure you've run npm run build

"EPCC is not configured" error

• Double-check your EPCC_CLIENT_ID, EPCC_CLIENT_SECRET, and EPCC_BASE_URL
• Ensure your EPCC application has the necessary permissions

"No data returned" responses

• Verify your date ranges use the correct format (RFC3339 with milliseconds)
• Check that you have data for the requested time period
• Ensure your EPCC client has access to the Data Warehouse service

Connection timeouts

• Your EPCC application may need Data Warehouse API access enabled
• Check your EPCC application's rate limits

Development

Build the server:

npm run build

Run with debugging:

npm run debug

Watch mode for development:

npm run dev

Requirements

• Node.js 18 or later
• An EPCC account with Data Warehouse access
• MCP-compatible client (such as Claude Desktop, Continue, or any client supporting the Model Context Protocol)

Made for the EPCC community. Questions? Open an issue or contribute improvements.

Additional Resources

• Elastic Path Composable Commerce Documentation - Official EPCC API documentation
• Model Context Protocol - MCP specification and guides
• EPCC Developer Portal - Implementation guides and tutorials