Bigcommerce Api Mcp

BigCommerce MCP 服务

一个用于 BigCommerce REST API 的 MCP 服务。为 AI 助手提供对商品目录、客户和订单的只读访问权限；启用后，还可更改这些内容。

工具

读取

工具	功能
get_all_products	列出商品，支持筛选、排序和分页
get_product	按 ID 获取单个商品，可选择包含变体和图片
get_all_customers	按 ID、邮箱、姓名、公司或日期范围列出客户
get_all_orders	按客户、状态、日期范围或总金额列出订单
get_order	按 ID 获取单个订单
get_order_products	获取订单的商品明细——实际购买的商品
list_categories	将分类名称解析为商品筛选所需的 ID
list_brands	将品牌名称解析为商品筛选所需的 ID

写入——需要设置 BIGCOMMERCE_ENABLE_WRITES=true

工具	功能
create_product	创建目录商品
update_product	更新价格、库存、可见性、分类等
create_customer	创建客户记录
update_customer	更新客户详细信息
update_order	更改状态、员工备注或客户消息

除非启用写入功能，否则根本不会注册写入工具。因此，即使有人访问了默认部署的端点，也无法修改你的商店。

运行 npm run list-tools 可打印当前配置的工具和参数。

设置

需要 Node 20+。

git clone https://github.com/isaacgounton/bigcommerce-api-mcp.git
cd bigcommerce-api-mcp
npm install
cp .env.example .env

然后填写 .env：

BIGCOMMERCE_STORE_HASH=your_store_hash_here
BIGCOMMERCE_API_KEY=your_api_key_here

在 BigCommerce 管理后台中获取这两项：Settings → API accounts → Create API account。授予 Products、Orders 和 Customers 权限；除非计划启用写入功能，否则使用只读权限。.env.example 记录了所有受支持的变量。

运行

npm start          # stdio — Claude Desktop, Cline, local clients
npm run start:http # streamable HTTP — remote clients and agent runtimes

HTTP 模式提供 POST /mcp，以及无需身份验证的 GET /health 和 /info。

SSE 传输已被移除，改用 Streamable HTTP；后者已在 MCP 规范中取代前者。仍在使用 /sse 的客户端应改为指向 /mcp。

Claude Desktop

在 claude_desktop_config.json 中配置（使用绝对路径——which node）：

{
  "mcpServers": {
    "bigcommerce": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/bigcommerce-api-mcp/mcpServer.js"],
      "env": {
        "BIGCOMMERCE_STORE_HASH": "your_store_hash",
        "BIGCOMMERCE_API_KEY": "your_api_key"
      }
    }
  }
}

通过 HTTP

curl -X POST http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

安全

任何能够调用 /mcp 的人都可以使用你商店的 API 凭据执行操作。

• HOST——默认绑定到 127.0.0.1。只有在确实需要对外开放时才设置为 0.0.0.0；开放时请将其置于代理或防火墙之后。
• MCP_AUTH_TOKEN——设置后，每个 /mcp 请求都必须携带 Authorization: Bearer <token>。比较过程采用时序安全方式。只要服务可从 localhost 以外的地方访问，就应设置此项。
• ALLOWED_ORIGINS——除非请求中的 Origin 标头列在此处，否则将拒绝该请求。这可以阻止 DNS 重绑定攻击，即你访问的网页驱动本地服务发起请求。不发送 Origin 的非浏览器客户端不受影响。
• **`BIGCOMMERCE_ENABLE_WRITES``——如果助手只需读取，请保持关闭。
• Scopes——为 API 账号授予能够正常工作的最小权限范围。只读令牌不会因该服务中的错误而获得更广泛的权限。

Docker

docker build -t bigcommerce-mcp .
docker run --rm -p 3000:3000 --env-file .env bigcommerce-mcp

镜像会设置 HOST=0.0.0.0，以便通过已发布的端口访问服务。对外开放容器前，请设置 MCP_AUTH_TOKEN。

开发

npm test           # protocol, auth, origin, discovery and spec conformance — no credentials needed
npm run test:live  # smoke-test read tools against a real store (needs .env)
npm run sync-spec  # refresh the query-parameter fixture from BigCommerce's OpenAPI specs

npm test 会根据 BigCommerce 发布的规范，检查工具声明的每个查询参数。这很重要，因为 BigCommerce 会忽略未知查询参数，而不是拒绝它们——虚构的筛选条件会悄无声息地返回未经筛选的数据，这比报错更糟。

要添加工具，请在 tools/bigcommerce/<group>/ 下放置一个导出 apiTool 的文件；系统会自动发现它。lib/bigcommerce.js 负责处理凭据、查询构建、错误和解析，因此工具通常只需定义路径和架构；可参考 tools/bigcommerce/catalog/list-brands.js。对于任何会修改商店的工具，请设置 writes: true。

MIT