Commerce Layer MCP Server for Metrics Analysis

Overview

This project provides a local Model Context Protocol (MCP) server tailored for analyzing Commerce Layer metrics. The server acts as a local bridge between AI agents (or local tooling) and the Commerce Layer Metrics API, exposing a collection of prebuilt tools that make it fast to query, aggregate, and inspect historical orders, carts, and returns data. Running this server locally helps with rapid iteration, debugging, and exploratory data-analysis workflows without requiring direct calls to the remote API from every script or agent.

The Metrics MCP Server ships with a set of query primitives (breakdowns, date breakdowns, stats and searches) implemented as MCP tools. These tools cover common analytics needs—top-sellers, cart activity, promotion attribution, error inspection—so you can compose reproducible queries and surface results directly inside a model-driven workflow or a local developer environment.

Features

• Local MCP server implementation compatible with Model Context Protocol hosts (e.g., Claude Desktop)
• Built-in metric tools to query Commerce Layer Metrics API for orders, carts, and returns
• Four query types: breakdown, date-breakdown, stats, and search
• Ready-made tools for common analytics tasks (best-sellers, frequently-bought-together, orders-by-currency, etc.)
• Bundling support for MCP hosts (pack an extension bundle for Claude Desktop)
• Lightweight install, build and packaging workflow; compiled output stored in dist/

Installation / Configuration

Clone, install dependencies, build, and prepare the MCP server:

# clone the repository
git clone https://github.com/commercelayer/mcp-server-metrics.git
cd mcp-server-metrics

# install dependencies (pnpm recommended)
pnpm install

# compile the project
pnpm build

# prepare the distributable files (produces dist/)
pnpm dist

If you plan to load the server as a Claude Desktop extension, create a bundle:

# build a packed MCP bundle (mcpb/commercelayer-metrics.mcpb)
npm run mcpb

Configuration notes

• During installation or when first invoked in an MCP host you will be prompted for Commerce Layer credentials (client_id and client_secret) to connect with your organization. Keep these secrets safe.
• The compiled server artifacts are under dist/. Depending on your host you may run the server from dist/ or upload the .mcpb bundle produced by npm run mcpb to Claude Desktop.

Example minimal environment variables (host-specific; adapt if your environment requires):

export COMMERCE_LAYER_CLIENT_ID="your_client_id"
export COMMERCE_LAYER_CLIENT_SECRET="your_client_secret"
export COMMERCE_LAYER_ORGANIZATION="your_organization_slug"

Available Resources

The server exposes tools that operate on three metric resources:

• orders
• carts
• returns

Each resource supports four query types:

Query Type	Purpose
breakdown	Aggregations grouped by a field (e.g., revenue by market)
date-breakdown	Time series aggregations by date (e.g., daily orders)
stats	Single-value statistics (sum, avg, count) over a field
search	Record search and listing (non-aggregated query & pagination)

Tool names follow the pattern: -, for example:

• orders-breakdown
• carts-date-breakdown
• returns-stats
• orders-search

Use Cases (concrete examples)

• Best-selling products by market

  • Tool: orders-breakdown
  • Description: aggregate sold quantities or revenue per product, grouped by market. Useful for identifying top SKUs per region.
  • Output: top-N products for each market with aggregated totals.

• Customers who bought a specific product

  • Tool: orders-search or orders-breakdown
  • Description: find unique customers (or count) who purchased a SKU or bundle within a time window.

• Frequently-bought-together products

  • Tool: orders-breakdown (co-occurrence or joins on order items)
  • Description: identify product pairs or groups commonly ordered together to inform bundling or recommendations.

• Latest archived or placed orders

  • Tool: orders-search
  • Description: return paginated recent orders filtered by state (archived, placed) with requested fields (customer, totals, items).

• Orders by currency or by day

  • Tool: orders-breakdown / orders-date-breakdown
  • Description: aggregate totals grouped by currency codes or daily buckets for trend analysis.

• Orders associated with a specific promotion

  • Tool: orders-breakdown or orders-search
  • Description: count or list orders where a given promotion triggered discounts; useful for measuring promotion performance.

• Debugging order errors

  • Tool: orders-search or orders-breakdown (group by error code)
  • Description: surface errors attached to order records to triage fulfillment or integration issues.

Example pseudo-request (date breakdown for daily order counts):

{
  "tool": "orders-date-breakdown",
  "params": {
    "field": "created_at",
    "operator": "count",
    "interval": "day",
    "from": "2025-01-01",
    "to": "2025-03-31"
  }
}

Tips for Developers

• Use the server locally when iterating on queries to avoid hitting rate limits and to make debugging easier.
• Combine multiple tools programmatically from an agent or a script to build dashboards or automated reports.
• When packaging for Claude Desktop, validate the bundle (mcpb/commercelayer-metrics.mcpb) before sharing the extension; the host will request client credentials on first connection.
• Review the Commerce Layer Metrics API docs for available fields and operators to craft effective breakdowns and stats: https://docs.commercelayer.io/metrics

Repository and source

• GitHub: https://github.com/commercelayer/mcp-server-metrics

This MCP server is intended to accelerate analysis workflows and provide reproducible, model-driven access to Commerce Layer metric data for both analytics and debugging scenarios.