Jake Shore e9ddbc24cc bigcommerce + keap: comprehensive READMEs with full tool counts

2026-02-12 17:33:17 -05:00

22 KiB

Raw Blame History

BigCommerce MCP Server

Complete Model Context Protocol (MCP) server for BigCommerce API with 148 production-ready tools and 24 interactive React apps covering the entire e-commerce platform.

🚀 Features

✅ 148 MCP Tools - Complete coverage of BigCommerce Catalog, Orders, Customers, Marketing, Shipping, and Store Configuration APIs
✅ 24 Interactive Apps - React-based UIs for product management, order fulfillment, customer engagement, analytics, and more
✅ Full TypeScript - End-to-end type safety with comprehensive BigCommerce type definitions
✅ Dual API Support - Seamless integration with both v2 (legacy) and v3 (modern) BigCommerce APIs
✅ Production Ready - Built-in rate limiting, error handling, retry logic, and connection pooling
✅ Zero Config - Works out of the box with environment variables

📦 Installation

npm install @mcpengine/bigcommerce

Or clone and build locally:

git clone https://github.com/BusyBee3333/mcpengine.git
cd mcpengine/servers/bigcommerce
npm install
npm run build

⚙️ Configuration

Environment Variables

Set the following required variables:

export BIGCOMMERCE_STORE_HASH="your-store-hash"
export BIGCOMMERCE_ACCESS_TOKEN="your-access-token"

Get Your API Credentials

Log in to your BigCommerce store admin panel
Navigate to Settings → API → Store-level API accounts
Click Create API Account → Create V2/V3 API Token
Select OAuth scopes (Products, Orders, Customers, Carts, Marketing, etc.)
Copy your Store Hash and Access Token
Store Hash format: abc123def (found in your store URL: store-{hash}.mybigcommerce.com)

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bigcommerce": {
      "command": "npx",
      "args": ["-y", "@mcpengine/bigcommerce"],
      "env": {
        "BIGCOMMERCE_STORE_HASH": "your-store-hash",
        "BIGCOMMERCE_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}

🛠️ Usage

Stdio Transport (Claude Desktop, Cline, etc.)

bigcommerce-mcp

Programmatic Usage

import { BigCommerceClient } from '@mcpengine/bigcommerce';

const client = new BigCommerceClient({
  storeHash: process.env.BIGCOMMERCE_STORE_HASH!,
  accessToken: process.env.BIGCOMMERCE_ACCESS_TOKEN!,
  apiVersion: 'v3', // or 'v2' for legacy endpoints
});

// Fetch products
const products = await client.get('/catalog/products?limit=50');
console.log(products);

🔧 MCP Tools (148 Total)

Products (22 tools)

Full product lifecycle management with variants, images, custom fields, and bulk pricing.

Tool	Description
`bigcommerce_list_products`	List products with filters (name, SKU, price, category, brand, inventory)
`bigcommerce_get_product`	Get product details with variants, images, custom fields
`bigcommerce_create_product`	Create new product with complete configuration
`bigcommerce_update_product`	Update existing product properties
`bigcommerce_delete_product`	Delete product from catalog
`bigcommerce_list_product_variants`	List all variants for a product
`bigcommerce_get_product_variant`	Get variant details (SKU, price, inventory)
`bigcommerce_create_product_variant`	Create new product variant
`bigcommerce_update_product_variant`	Update variant properties
`bigcommerce_delete_product_variant`	Delete variant
`bigcommerce_list_product_images`	List product images
`bigcommerce_create_product_image`	Upload product image
`bigcommerce_update_product_image`	Update image properties (sort order, description)
`bigcommerce_delete_product_image`	Delete product image
`bigcommerce_list_product_custom_fields`	List custom fields for a product
`bigcommerce_create_product_custom_field`	Add custom field to product
`bigcommerce_update_product_custom_field`	Update custom field value
`bigcommerce_delete_product_custom_field`	Remove custom field
`bigcommerce_list_product_bulk_pricing`	List bulk pricing rules
`bigcommerce_create_product_bulk_pricing`	Create bulk pricing rule
`bigcommerce_update_product_bulk_pricing`	Update bulk pricing rule
`bigcommerce_delete_product_bulk_pricing`	Delete bulk pricing rule

Orders (17 tools)

Complete order management, fulfillment, shipping, and refund processing.

Tool	Description
`bigcommerce_list_orders`	List orders with status, date, customer filters
`bigcommerce_get_order`	Get order details with line items and addresses
`bigcommerce_create_order`	Create new order programmatically
`bigcommerce_update_order`	Update order status and properties
`bigcommerce_delete_order`	Archive order
`bigcommerce_list_order_products`	List products in an order
`bigcommerce_get_order_product`	Get order line item details
`bigcommerce_list_order_shipping_addresses`	List shipping addresses for order
`bigcommerce_get_order_shipping_address`	Get shipping address details
`bigcommerce_update_order_shipping_address`	Update shipping address
`bigcommerce_list_order_shipments`	List shipments for order
`bigcommerce_create_order_shipment`	Create shipment with tracking
`bigcommerce_update_order_shipment`	Update shipment tracking
`bigcommerce_delete_order_shipment`	Remove shipment
`bigcommerce_list_order_coupons`	List coupons applied to order
`bigcommerce_create_order_refund`	Process full or partial refund
`bigcommerce_get_order_count`	Get total order count with filters

Customers (17 tools)

Customer profiles, addresses, groups, segments, and authentication.

Tool	Description
`bigcommerce_list_customers`	List customers with name, email, group filters
`bigcommerce_get_customer`	Get customer profile with addresses
`bigcommerce_create_customer`	Create new customer account
`bigcommerce_update_customer`	Update customer details
`bigcommerce_delete_customer`	Delete customer account
`bigcommerce_list_customer_addresses`	List customer addresses
`bigcommerce_get_customer_address`	Get address details
`bigcommerce_create_customer_address`	Add new address
`bigcommerce_update_customer_address`	Update address
`bigcommerce_delete_customer_address`	Remove address
`bigcommerce_list_customer_groups`	List customer groups
`bigcommerce_get_customer_group`	Get group details
`bigcommerce_create_customer_group`	Create customer group
`bigcommerce_update_customer_group`	Update group properties
`bigcommerce_delete_customer_group`	Delete group
`bigcommerce_list_customer_segments`	List dynamic customer segments
`bigcommerce_validate_customer_password`	Validate password strength

Carts & Checkout (16 tools)

Shopping cart management, checkout flow, and cart-to-order conversion.

Tool	Description
`bigcommerce_create_cart`	Create new shopping cart
`bigcommerce_get_cart`	Get cart contents and totals
`bigcommerce_update_cart`	Update cart properties
`bigcommerce_delete_cart`	Delete cart
`bigcommerce_add_cart_items`	Add products to cart
`bigcommerce_update_cart_item`	Update cart item quantity/options
`bigcommerce_delete_cart_item`	Remove item from cart
`bigcommerce_create_checkout`	Convert cart to checkout
`bigcommerce_get_checkout`	Get checkout details
`bigcommerce_update_checkout`	Update checkout properties
`bigcommerce_add_checkout_billing_address`	Add billing address to checkout
`bigcommerce_add_checkout_consignment`	Add shipping consignment
`bigcommerce_update_checkout_consignment`	Update consignment
`bigcommerce_delete_checkout_consignment`	Remove consignment
`bigcommerce_create_checkout_order`	Finalize checkout and create order
`bigcommerce_create_cart_redirect_url`	Generate checkout redirect URL

Catalog Organization (13 tools)

Categories, brands, and bulk catalog operations.

Tool	Description
`bigcommerce_list_categories`	List categories with filters
`bigcommerce_get_category`	Get category details
`bigcommerce_create_category`	Create new category
`bigcommerce_update_category`	Update category properties
`bigcommerce_delete_category`	Delete category
`bigcommerce_get_category_tree`	Get complete category hierarchy
`bigcommerce_list_brands`	List brands with filters
`bigcommerce_get_brand`	Get brand details
`bigcommerce_create_brand`	Create new brand
`bigcommerce_update_brand`	Update brand properties
`bigcommerce_delete_brand`	Delete brand
`bigcommerce_bulk_update_product_prices`	Bulk price update across products
`bigcommerce_bulk_delete_products`	Bulk product deletion

Promotions & Marketing (19 tools)

Coupons, promotions, gift certificates, and wishlists.

Tool	Description
`bigcommerce_list_promotions`	List active promotions
`bigcommerce_get_promotion`	Get promotion details
`bigcommerce_create_promotion`	Create new promotion
`bigcommerce_update_promotion`	Update promotion rules
`bigcommerce_delete_promotion`	Delete promotion
`bigcommerce_list_coupons`	List coupon codes
`bigcommerce_get_coupon`	Get coupon details
`bigcommerce_create_coupon`	Create coupon code
`bigcommerce_update_coupon`	Update coupon properties
`bigcommerce_delete_coupon`	Delete coupon
`bigcommerce_list_gift_certificates`	List gift certificates
`bigcommerce_get_gift_certificate`	Get gift certificate details
`bigcommerce_create_gift_certificate`	Issue gift certificate
`bigcommerce_update_gift_certificate`	Update gift certificate
`bigcommerce_delete_gift_certificate`	Void gift certificate
`bigcommerce_list_wishlists`	List customer wishlists
`bigcommerce_get_wishlist`	Get wishlist items
`bigcommerce_add_wishlist_item`	Add product to wishlist
`bigcommerce_delete_wishlist_item`	Remove wishlist item

Shipping & Fulfillment (17 tools)

Shipping zones, methods, tax classes, payment methods, and currencies.

Tool	Description
`bigcommerce_list_shipping_zones`	List shipping zones
`bigcommerce_get_shipping_zone`	Get zone details
`bigcommerce_create_shipping_zone`	Create shipping zone
`bigcommerce_update_shipping_zone`	Update zone properties
`bigcommerce_delete_shipping_zone`	Delete zone
`bigcommerce_list_shipping_methods`	List methods for zone
`bigcommerce_create_shipping_method`	Create shipping method
`bigcommerce_update_shipping_method`	Update method rates
`bigcommerce_delete_shipping_method`	Remove method
`bigcommerce_list_tax_classes`	List tax classes
`bigcommerce_get_tax_class`	Get tax class details
`bigcommerce_list_payment_methods`	List enabled payment gateways
`bigcommerce_list_currencies`	List store currencies
`bigcommerce_get_currency`	Get currency details
`bigcommerce_create_currency`	Add new currency
`bigcommerce_update_currency`	Update currency settings
`bigcommerce_delete_currency`	Remove currency

Store Management (11 tools)

Store information, channels, sites, and timezone configuration.

Tool	Description
`bigcommerce_get_store_information`	Get store profile and settings
`bigcommerce_list_channels`	List sales channels (web, marketplace)
`bigcommerce_get_channel`	Get channel details
`bigcommerce_create_channel`	Create new channel
`bigcommerce_update_channel`	Update channel settings
`bigcommerce_list_sites`	List channel sites
`bigcommerce_get_site`	Get site configuration
`bigcommerce_create_site`	Create new site
`bigcommerce_update_site`	Update site settings
`bigcommerce_delete_site`	Remove site
`bigcommerce_get_time_zone`	Get store timezone

Content Management (10 tools)

Scripts (analytics, tracking) and CMS pages.

Tool	Description
`bigcommerce_list_scripts`	List store scripts (Google Analytics, etc.)
`bigcommerce_get_script`	Get script details
`bigcommerce_create_script`	Add new script to store
`bigcommerce_update_script`	Update script properties
`bigcommerce_delete_script`	Remove script
`bigcommerce_list_pages`	List CMS pages
`bigcommerce_get_page`	Get page content
`bigcommerce_create_page`	Create CMS page
`bigcommerce_update_page`	Update page content/SEO
`bigcommerce_delete_page`	Delete CMS page

Webhooks (6 tools)

Event-driven integration with external systems.

Tool	Description
`bigcommerce_list_webhooks`	List active webhooks
`bigcommerce_get_webhook`	Get webhook configuration
`bigcommerce_create_webhook`	Register webhook for events
`bigcommerce_update_webhook`	Update webhook URL/events
`bigcommerce_delete_webhook`	Remove webhook
`bigcommerce_list_webhook_scopes`	List available webhook events

🎨 React Apps (24 Total)

Product Management

App	Description
product-grid	Searchable product grid with bulk actions (price update, inventory sync, category assignment)
product-dashboard	Product performance metrics with sales charts and inventory alerts
product-detail	Complete product editor with variant manager, image uploader, and SEO optimizer
inventory-tracker	Real-time inventory tracking with low-stock alerts and reorder suggestions
category-tree	Drag-and-drop category hierarchy editor with product assignment
brand-manager	Brand library with logo upload, description editor, and product count

Order Management

App	Description
order-grid	Paginated order list with status filters and quick actions (fulfill, refund)
order-dashboard	Sales performance dashboard with revenue charts and order velocity
order-detail	Complete order view with timeline, line items, customer info, and fulfillment tracking
cart-viewer	Real-time abandoned cart monitor with recovery email triggers

Customer Engagement

App	Description
customer-grid	Customer directory with segmentation filters and bulk email actions
customer-detail	360° customer profile with order history, lifetime value, and wishlist

Marketing & Promotions

App	Description
coupon-manager	Coupon code generator with usage tracking and ROI analysis
content-pages	CMS page editor with SEO preview and publish scheduling
blog-manager	Blog post management with rich text editor and tag system

Analytics & Reporting

App	Description
analytics-dashboard	Store-wide KPIs: revenue, conversion rate, AOV, customer acquisition
revenue-dashboard	Revenue breakdown by product, category, channel, and time period

Configuration

App	Description
channel-manager	Multi-channel listing manager (Amazon, eBay, Facebook) with sync status
shipping-manager	Shipping zone/method configurator with rate calculator
store-overview	Store health dashboard with API usage, webhook status, and system alerts

Developer Tools

App	Description
webhook-monitor	Real-time webhook event viewer with payload inspection and retry
api-explorer	Interactive API browser with request/response viewer
data-export	Bulk data export tool for products, orders, customers (CSV/JSON)

📊 API Coverage

This MCP server provides comprehensive access to:

Catalog API (v3)

Products, Variants, Images, Videos
Categories, Category Trees
Brands
Product Modifiers, Custom Fields
Bulk Pricing Rules

Orders API (v2)

Orders, Order Products
Shipments, Tracking
Order Statuses
Refunds

Customers API (v3)

Customers, Addresses
Customer Groups, Segments
Customer Attributes
Authentication & Passwords

Carts API (v3)

Server-to-Server Carts
Cart Items, Line Items
Checkout, Billing Address
Consignments (Shipping)

Marketing API (v2/v3)

Promotions
Coupons
Gift Certificates
Wishlists

Channels API (v3)

Sales Channels
Channel Listings
Sites & Routes

Store Information API (v2)

Store Profile
Store Time Zone
Store Features

Shipping API (v2)

Shipping Zones
Shipping Methods
Custom Shipping Carriers

Payment Processing API (v3)

Payment Methods
Stored Instruments

Webhooks API (v3)

Webhook Management
Event Subscriptions

Content API (v3)

Scripts (Analytics, Tracking)
Pages (CMS)

🔐 Rate Limits & Best Practices

BigCommerce Rate Limits

Standard Plan: 20,000 requests/hour
Plus/Pro Plans: Higher limits (contact BigCommerce)
Burst Limit: 150 requests/30 seconds

Built-in Handling

The client automatically:

✅ Tracks rate limit headers (X-Rate-Limit-Requests-Left, X-Rate-Limit-Time-Reset-Ms)
✅ Implements exponential backoff on 429 (Too Many Requests)
✅ Retries failed requests up to 3 times
✅ Respects Retry-After headers

Optimization Tips

Use pagination (limit=250) for large datasets
Use field filters (include=variants,images) to reduce payload size
Cache frequently accessed data (store info, categories)
Batch operations where possible (bulk price updates)
Use webhooks instead of polling for real-time events

🛡️ Error Handling

Comprehensive error handling for all failure scenarios:

HTTP Status	Meaning	Client Behavior
400	Bad Request	Returns validation error details
401	Unauthorized	Check `BIGCOMMERCE_ACCESS_TOKEN`
403	Forbidden	Token missing required OAuth scope
404	Not Found	Resource doesn't exist
409	Conflict	Duplicate SKU or unique constraint violation
422	Unprocessable Entity	Validation failed (returns field errors)
429	Too Many Requests	Auto-retry with exponential backoff
500	Server Error	Retry up to 3 times
503	Service Unavailable	BigCommerce maintenance mode

All errors include:

Human-readable error message
HTTP status code
Request ID (for BigCommerce support)
Field-level validation errors (when applicable)

🏗️ Architecture

bigcommerce-mcp/
├── src/
│   ├── clients/
│   │   └── bigcommerce.ts          # HTTP client with rate limiting
│   ├── tools/
│   │   ├── products-tools.ts       # 22 product tools
│   │   ├── orders-tools.ts         # 17 order tools
│   │   ├── customers-tools.ts      # 17 customer tools
│   │   ├── carts-tools.ts          # 16 cart/checkout tools
│   │   ├── catalog-tools.ts        # 13 catalog tools
│   │   ├── promotions-tools.ts     # 19 marketing tools
│   │   ├── shipping-tools.ts       # 17 shipping/fulfillment tools
│   │   ├── store-tools.ts          # 11 store management tools
│   │   ├── content-tools.ts        # 10 CMS tools
│   │   └── webhooks-tools.ts       # 6 webhook tools
│   ├── types/
│   │   └── index.ts                # BigCommerce type definitions
│   ├── ui/
│   │   └── react-app/              # 24 React apps
│   ├── server.ts                   # MCP server implementation
│   └── main.ts                     # CLI entry point
├── package.json
├── tsconfig.json
└── README.md

Type Safety

All tools use TypeScript interfaces matching BigCommerce API schemas:

Product, ProductVariant, ProductImage
Order, OrderProduct, Shipment
Customer, CustomerAddress, CustomerGroup
Cart, Checkout, LineItem
And 40+ more types

🚀 Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Build React apps
npm run build:ui

# Run in development mode
npm run dev

# Lint code
npm run lint

# Run tests
npm test

Adding New Tools

Create tool file in src/tools/ (e.g., my-tools.ts)
Export registerMyTools(client) function
Import and register in src/server.ts
Add TypeScript types in src/types/
Rebuild: npm run build

📝 License

🆘 Support & Resources

GitHub: https://github.com/BusyBee3333/mcpengine
Issues: https://github.com/BusyBee3333/mcpengine/issues
BigCommerce API Docs: https://developer.bigcommerce.com/docs/rest
BigCommerce Dev Center: https://developer.bigcommerce.com
MCP Specification: https://modelcontextprotocol.io

Common Issues

❌ "Missing required environment variables" → Set BIGCOMMERCE_STORE_HASH and BIGCOMMERCE_ACCESS_TOKEN environment variables.

❌ "401 Unauthorized" → Check your access token is valid and not expired. Regenerate in BigCommerce admin if needed.

❌ "403 Forbidden" → Your API token is missing required OAuth scopes. Edit the API account and grant additional permissions.

❌ "429 Too Many Requests" → You've hit BigCommerce rate limits. The client will auto-retry with backoff. Consider upgrading your plan for higher limits.

❌ "SSL certificate verification failed" → Your store hash or domain is incorrect. Verify the store hash matches your store URL.

🎯 Roadmap

Add GraphQL Storefront API support
Implement bulk import/export (CSV)
Add product recommendation engine tools
Create customer segmentation wizard
Add A/B testing tools for promotions
Implement multi-currency conversion tools
Add headless commerce tools (Next.js integration)

Built with ❤️ by BusyBee3333 | Powered by Model Context Protocol

22 KiB Raw Blame History