BigCommerce MCP Server

An MCP server for the BigCommerce REST API. Gives an AI assistant read access to your catalog, customers and orders — and, when you turn it on, the ability to change them.

Tools

Read

Tool	What it does
get_all_products	List products with filtering, sorting and pagination
get_product	One product by ID, optionally with variants and images
get_all_customers	List customers by ID, email, name, company or date range
get_all_orders	List orders by customer, status, date range or total
get_order	One order by ID
get_order_products	An order's line items — what was actually bought
list_categories	Resolve category names to the IDs product filters need
list_brands	Resolve brand names to the IDs product filters need

Write — requires BIGCOMMERCE_ENABLE_WRITES=true

Tool	What it does
create_product	Create a catalog product
update_product	Update price, stock, visibility, categories…
create_customer	Create a customer record
update_customer	Update a customer's details
update_order	Change status, staff notes or customer message

Write tools aren't registered at all unless enabled, so a default deployment can't modify your store even if someone reaches its endpoint.

npm run list-tools prints the tools and parameters as currently configured.

Setup

Needs Node 20+.

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

Then fill in .env:

BIGCOMMERCE_STORE_HASH=your_store_hash_here
BIGCOMMERCE_API_KEY=your_api_key_here

Get both from BigCommerce admin → Settings → API accounts → Create API account. Grant Products, Orders and Customers — read-only unless you plan to enable writes. .env.example documents every supported variable.

Running

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

HTTP mode serves POST /mcp, plus unauthenticated GET /health and /info.

The SSE transport was removed in favour of Streamable HTTP, which replaced it in the MCP spec. Point any client still using /sse at /mcp.

Claude Desktop

In claude_desktop_config.json (use absolute paths — 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"
      }
    }
  }
}

Over 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"}'

Security

Anyone who can call /mcp acts with your store's API credentials.

• HOST — binds to 127.0.0.1 by default. Set 0.0.0.0 only when you mean to expose it, and put it behind a proxy or firewall when you do.
• MCP_AUTH_TOKEN — when set, every /mcp request must carry Authorization: Bearer <token>. Comparison is timing-safe. Set it whenever the server is reachable beyond localhost.
• ALLOWED_ORIGINS — requests carrying an Origin header are refused unless listed here, which blocks DNS-rebinding attacks where a page you visit drives your local server. Non-browser clients send no Origin and are unaffected.
• BIGCOMMERCE_ENABLE_WRITES — leave off if the assistant only reads.
• Scopes — give the API account the narrowest scopes that work. A read-only token can't be widened by a bug in this server.

Docker

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

The image sets HOST=0.0.0.0 so the published port is reachable. Set MCP_AUTH_TOKEN before exposing the container.

Development

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 checks every query parameter a tool declares against BigCommerce's published specs. This matters because BigCommerce ignores unknown query parameters rather than rejecting them — an invented filter silently returns unfiltered data, which is worse than an error.

To add a tool, drop a file under tools/bigcommerce/<group>/ exporting an apiTool — it's discovered automatically. lib/bigcommerce.js handles credentials, query building, errors and parsing, so a tool is usually just a path and a schema; copy tools/bigcommerce/catalog/list-brands.js. Set writes: true on anything that mutates the store.

MIT