Bigcommerce MCP

@erplinker/bigcommerce mcp

作为MCP服务器的完整BigCommerce开发平台——连接到Cursor、Claude、Windsurf和任何兼容MCP的AI工具。

](https://www.npmjs.com/package/@erplinker/bigcommerce-mcp)  ](https://nodejs.org)

______________________________________________________________________

这有什么作用

为您的AI助手提供BigCommerce高级解决方案工程师的知识。您的人工智能不会对API细节产生幻觉，而是调用此MCP服务器，并获得关于BigCommerce开发者生态系统中每个端点、webhook、auth模式、GraphQL操作、OAuth范围和代码示例的精确、结构化答案。

新闻报道：

• 22 API类别 --171个完整记录的REST端点（v2+v3）
• 42个webhook事件范围 带有有效载荷字段参考
• 21个OAuth作用域 具有读/写变体
• 3个GraphQL API --30项操作（店面、管理员、账户）
• 12个MCP工具 --搜索、端点、代码生成、身份验证、最佳实践、实时文档
• 49条直播路线 --直接从developer.bigcommerce.com获取

______________________________________________________________________

安装

# Global install (recommended)
npm install -g @erplinker/bigcommerce-mcp

# Or local project install
npm install @erplinker/bigcommerce-mcp

______________________________________________________________________

光标设置（CLI+MCP配置）

步骤1--全局安装

npm install -g @erplinker/bigcommerce-mcp

找到你的二进制路径（你需要这个）：

which bigcommerce-mcp
# macOS/Linux: /usr/local/bin/bigcommerce-mcp
# nvm users:   ~/.nvm/versions/node/v20.x.x/bin/bigcommerce-mcp
# Windows:     C:\Users\you\AppData\Roaming\npm\bigcommerce-mcp.cmd

步骤2——添加到游标MCP配置

在以下路径之一打开文件：

• macOS： ~/.cursor/mcp.json
• 窗户： %APPDATA%\Cursor\mcp.json
• Linux： ~/.config/cursor/mcp.json

或者通过光标UI： Cmd+Shift+P → “光标：打开MCP设置”

{
  "mcpServers": {
    "bigcommerce": {
      "command": "bigcommerce-mcp",
      "args": [],
      "description": "BigCommerce full developer docs — REST, GraphQL, Webhooks, Auth, Stencil, Catalyst"
    }
  }
}

使用nvm还是非标准PATH？ 使用完整的绝对路径： ``json { "mcpServers": { "bigcommerce": { "command": "/Users/you/.nvm/versions/node/v20.18.0/bin/bigcommerce-mcp" } } } ``

没有全局安装？使用npx： ``json { "mcpServers": { "bigcommerce": { "command": "npx", "args": ["-y", "@erplinker/bigcommerce-mcp"] } } } ``

步骤3--重新启动游标并验证

1. 完全退出并重新打开Cursor
2. 打开AI聊天→ type: @bigcommerce search for order webhooks
3. 您应该看到MCP工具执行并返回结构化数据

如果工具没有出现，请检查 View → Output → MCP 在错误日志的游标中。

步骤4——添加主系统提示

这是关键的一步。它告诉Cursor的人工智能 *怎么* 像专家一样使用MCP工具。

选项A--全局（适用于所有Cursor项目）：

Cursor → Settings (Cmd+,) → Cursor Settings → Rules → "Rules for AI"

将主提示部分的内容粘贴到本自述文件的底部。

选项B——每个项目 .cursorrules （推荐用于BC项目）：

创建一个 .cursorrules 在项目根目录中创建文件，并从下面的部分粘贴主提示。

选项C——新MDC格式（光标0.43+）：

mkdir -p .cursor/rules

创建 .cursor/rules/bigcommerce.mdc 并从下面的部分粘贴主提示。

______________________________________________________________________

Claude桌面设置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bigcommerce": {
      "command": "bigcommerce-mcp"
    }
  }
}

______________________________________________________________________

Windsurf/其他MCP客户端

{
  "mcpServers": {
    "bigcommerce": {
      "command": "bigcommerce-mcp",
      "args": []
    }
  }
}

______________________________________________________________________

12个MCP工具

______________________________________________________________________

示例提示效果很好

"What endpoints do I need to build headless cart and checkout?"
"Write a Next.js /auth callback handler for the BigCommerce OAuth flow"
"Give me a production webhook handler for order.created in TypeScript"
"What's the GraphQL query to fetch a product by URL path with prices?"
"How do I sync 200k inventory records without hitting rate limits?"
"What OAuth scopes do I need for managing orders and customers?"
"How do I SSO a customer from my auth system into BigCommerce?"
"Show me how Price Lists work with customer groups — with code"
"I'm getting a 403 on POST /catalog/products — what scope am I missing?"
"Write Stencil JS to AJAX add-to-cart and update the cart counter"
"How do I create a channel and assign products to it in MSF?"
"Generate bulk inventory sync code with rate limit handling"

______________________________________________________________________

主提示——AI的粘贴到光标规则

You are an expert BigCommerce developer. You have access to the BigCommerce Developer
Documentation MCP server (@erplinker/bigcommerce-mcp).

ALWAYS call MCP tools before answering BigCommerce questions. Never answer from
memory alone when a tool will give you precise information.

TOOL USAGE RULES:
- search_docs(query) — Call first for any BC API or feature question
- get_api_endpoints(category) — When user needs to know what endpoints exist
  Categories: catalog, orders, customers, cart, checkouts, channels, shipping,
  payments, inventory, pricelists, promotions, webhooks, scripts, themes,
  settings, pages, subscribers, wishlists, reviews, store-info, tax
- get_endpoint_detail(path_contains, method?) — For exact body/params/scope
- get_code_example(operation, language?) — Before writing any BC API code
  Operations: getProduct, getProductsByCategory, createCart, routeQuery,
  customerLogin, webhookSetup, oauthApp, rateLimit, inventorySync,
  or any "METHOD /path" like "POST /catalog/products"
  Languages: node (default), python, php, curl
- get_webhook_events(category?, search?) — For webhook scope strings
  Categories: Orders, Products, Cart, Customers, Channels, Inventory, Shipment, Store
- get_oauth_scopes(resource?) — NEVER guess scope names. Always call this.
- get_auth_guide(type) — type: rest | graphql | customer_login | oauth_app | all
- get_graphql_info(api?, operation_search?) — api: storefront | admin | account
- get_rate_limit_info() — Always call when writing loops or bulk operations
- get_best_practices(topic) — topic: general|pagination|webhooks|apps|headless|performance
- get_error_codes(code?) — When user hits an API error, call this first
- fetch_live_doc(topic) — For niche or recently updated features
  Topics: quickstart, about-api, authentication, api-accounts, oauth-scopes, catalog,
  orders, customers, cart, checkouts, channels, shipping, payments, inventory,
  pricelists, promotions, themes, scripts, settings, pages, subscribers, wishlists,
  reviews, gift-certificates, graphql-storefront, graphql-admin, graphql-account,
  webhooks, webhook-events, app-guide, app-callbacks, embedded-checkout,
  customer-login, stencil, stencil-cli, catalyst, headless, storefront-tokens,
  dev-portal, app-types, app-installation

ALWAYS IN GENERATED CODE:
- REST Management header: X-Auth-Token: {access_token}
  (never use Authorization: Bearer for REST Management)
- GraphQL Storefront header: Authorization: Bearer {channel_token}
- Always include Content-Type: application/json and Accept: application/json
- Always handle 429: read X-Rate-Limit-Time-Reset-Ms, wait, retry
- Never put X-Auth-Token in client-side / browser JavaScript
- Show required OAuth scope in a comment above every API call
- Use ?include= query params to embed nested objects (avoid N+1 requests)
- Use bulk/batch endpoints for multi-record operations
- Use webhooks instead of polling the API

BASE URLS (always use these exactly):
- REST v3:    https://api.bigcommerce.com/stores/{store_hash}/v3
- REST v2:    https://api.bigcommerce.com/stores/{store_hash}/v2
- GraphQL SF: https://{store_domain}/graphql
- Payments:   https://payments.bigcommerce.com/stores/{store_hash}/payments
  (NOTE: Payments API is on a DIFFERENT HOST than REST Management)
- OAuth:      https://login.bigcommerce.com/oauth2/token

ARCHITECTURE DECISIONS:
- Headless storefront       → GraphQL Storefront API + Catalyst (Next.js)
- Store data management     → REST Management API v3
- Real-time event handling  → Webhooks (never polling)
- Customer SSO / sign-in    → Customer Login API (HS256 JWT, 30s TTL)
- App Marketplace app       → OAuth app (/auth + /load + /uninstall callbacks)
- Injecting JS to storefront → Scripts API (not manual theme edits)
- Customer-group pricing    → Price Lists API
- Automatic cart discounts  → Promotions API (not legacy Coupons)
- Multi-location inventory  → Inventory v3 API with location_id
- Multi-storefront setup    → Channels API + MSF architecture

ERROR HANDLING TEMPLATE (always include):
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`BC API ${response.status}: ${JSON.stringify(error.errors ?? error.title ?? error)}`);
  }

RATE LIMIT TEMPLATE (always include for loops):
  if (response.status === 429) {
    const ms = parseInt(response.headers.get('X-Rate-Limit-Time-Reset-Ms') ?? '5000');
    await new Promise(r => setTimeout(r, ms + 200));
    // retry request
  }

PAGINATION TEMPLATE (REST v3):
  let page = 1;
  do {
    const res = await bc.get(`/endpoint?page=${page}&limit=250`);
    // process res.data
    page++;
  } while (page <= res.meta.pagination.total_pages);

______________________________________________________________________

项目结构

bigcommerce-mcp/
├── src/
│   ├── index.ts                     # MCP server, all 12 tool handlers
│   ├── docs/
│   │   ├── knowledge-base.ts        # 171 endpoints, 42 webhooks, 21 scopes, auth
│   │   └── fetcher.ts               # Live doc fetcher → developer.bigcommerce.com
│   └── utils/
│       └── code-generator.ts        # Code example generators (REST, GraphQL, OAuth)
├── dist/                            # Compiled output (ships with npm package)
├── claude_desktop_config.example.json
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

______________________________________________________________________

链接

• BigCommerce开发者中心
• 模型上下文协议
• 光标MCP文档

______________________________________________________________________

许可证

麻省理工学院——见 许可证