[!IMPORTANT] Commerce MCP is provided free of charge as an early access service. Our Service Level Agreement do not apply to Commerce MCP, and it is provided on an "as-is" basis.

commercetools MCP Essentials

This repository contains both a MCP server (which you can integrate with many MCP clients) and agent essentials that can be used from within agent frameworks.

commercetools Model Context Protocol

Setup

To run the commercetools MCP server using npx, use the following command:

Client Credentials Authentication (Default)

# To set up all available tools (authType is optional, defaults to client_credentials)
npx -y @commercetools/mcp-essentials --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# Explicitly specify client_credentials (optional)
npx -y @commercetools/mcp-essentials --tools=all --authType=client_credentials --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up all read-only tools
npx -y @commercetools/mcp-essentials --tools=all.read --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up specific tools
npx -y @commercetools/mcp-essentials --tools=products.read,products.create --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Access Token Authentication

# To set up all available tools with access token
npx -y @commercetools/mcp-essentials --tools=all --authType=auth_token --accessToken=ACCESS_TOKEN --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

# To set up all read-only tools with access token
npx -y @commercetools/mcp-essentials --tools=all.read --authType=auth_token --accessToken=ACCESS_TOKEN --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Make sure to replace CLIENT_ID, CLIENT_SECRET, PROJECT_KEY, AUTH_URL, API_URL, and ACCESS_TOKEN with your actual values. If using the customerId parameter, replace CUSTOMER_ID with the actual customer ID. Alternatively, you could set the API_KEY in your environment variables.

To view information on how to develop the MCP server, see this README.<br> To view information on how to locally run the bootstrapped MCP server, see this README.

[!IMPORTANT] To load all the available tools set --tools=all and --isAdmin=true, all the available tools will be loaded into the MCP server. To limit the number of loaded tools set --tools=all.read for read-only tools or --tools=carts.read,quote.create,quote.read,... To disable dynamic tools loading set the dynamicToolLoadingThreshold to a very high value e.g --dynamicToolLoadingThreshold=650.

To view information on how to develop the MCP server, see this README.<br> To view information on how to locally run the bootstrapped MCP server, see this README.

Refer to our official public documentation for a more advanced and comprehensive guide on how to get the most out of our MCP offerings.

<!--

Authentication Options

The MCP server supports two authentication methods:

Authentication Type	Required Arguments	Description
client_credentials (default)	--clientId, --clientSecret	Uses API client credentials for authentication. --authType=client_credentials is optional since this is the default
auth_token	--accessToken, (optional --clientId, --clientSecret)	Uses a pre-existing access token for authentication. Requires --authType=auth_token and optional --clientId and --clientSecret

Usage with Claude Desktop

Add the following to your claude_desktop_config.json. See here for more details.

Client Credentials Authentication

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/mcp-essentials@latest",
        "--tools=all",
        "--clientId=CLIENT_ID",
        "--clientSecret=CLIENT_SECRET",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL",
        "--dynamicToolLoadingThreshold=30"
      ]
    }
  }
}

Note: You can optionally add "--authType=client_credentials" to be explicit, but it's not required since this is the default.

Access Token Authentication

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/mcp-essentials@latest",
        "--tools=all",
        "--authType=auth_token",
        "--accessToken=ACCESS_TOKEN",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL"
      ]
    }
  }
}

Alternative: To use only read-only tools, replace "--tools=all" with "--tools=all.read"

Available tools

Special Tool Options

Tool	Description
all	Enable all available tools (read, create, and update operations)
all.read	Enable all read-only tools (safe for read-only access)

Individual Tools

Tool	Description
products.read	Read product information
products.create	Create product information
products.update	Update product information
project.read	Read project information
product-search.read	Search products
category.read	Read category information
category.create	Create category
category.update	Update category
channel.read	Read channel information
channel.create	Create channel
channel.update	Update channel information
product-selection.read	Read product selection
product-selection.create	Create product selection
product-selection.update	Update product selection
order.read	Read order information
order.create	Create order (from cart, quote, import)
order.update	Update order information
cart.read	Read cart information
cart.create	Create cart
cart.update	Update cart information
customer.read	Read customer information
customer.create	Create customer
customer.update	Update customer information
customer-group.read	Read customer group
customer-group.create	Create customer group
customer-group.update	Update customer group
quote.read	Read quote information
quote.create	Create quote
quote.update	Update quote information
quote-request.read	Read quote request
quote-request.create	Create quote request
quote-request.update	Update quote request
staged-quote.read	Read staged quote
staged-quote.create	Create staged quote
staged-quote.update	Update staged quote
standalone-price.read	Read standalone price
standalone-price.create	Create standalone price
standalone-price.update	Update standalone price
product-discount.read	Read product discount
product-discount.create	Create product discount
product-discount.update	Update product discount
cart-discount.read	Read cart discount
cart-discount.create	Create cart discount
cart-discount.update	Update cart discount
discount-code.read	Read discount code information
discount-code.create	Create discount code
discount-code.update	Update discount code information
product-type.read	Read product type
product-type.create	Create product type
product-type.update	Update product type
bulk.create	Create entities in bulk
bulk.update	Update entities in bulk
inventory.read	Read inventory information
inventory.create	Create inventory
inventory.update	Update inventory information
store.read	Read store
store.create	Create store
store.update	Update store
business-unit.read	Read business unit
business-unit.create	Create business unit
business-unit.update	Update business unit
payments.read	Read payment information
payments.create	Create payment
payments.update	Update payment information
tax-category.read	Read tax category information
tax-category.create	Create tax category
tax-category.update	Update tax category information
shipping-methods.read	Read shipping method information
shipping-methods.create	Create shipping method
shipping-methods.update	Update shipping method information
zones.read	Read zone information
zones.create	Create zone
zones.update	Update zone information
recurring-orders.read	Read recurring order information
recurring-orders.create	Create recurring order
recurring-orders.update	Update recurring order information
shopping-lists.read	Read shopping list information
shopping-lists.create	Create shopping list
shopping-lists.update	Update shopping list information
extensions.read	Read extension information
extensions.create	Create extension
extensions.update	Update extension information
subscriptions.read	Read subscription information
subscriptions.create	Create subscription
subscriptions.update	Update subscription information
payment-methods.read	Read payment method information
payment-methods.create	Create payment method
payment-methods.update	Update payment method information
product-tailoring.read	Read product tailoring information
product-tailoring.create	Create product tailoring
product-tailoring.update	Update product tailoring information
custom-objects.read	Read custom object information
custom-objects.create	Create custom object
custom-objects.update	Update custom object information
types.read	Read type information
types.create	Create type
types.update	Update type information

To view information on how to develop the MCP server, see this README.

Dynamic Tool Loading

The MCP server includes a dynamic tool loading feature that automatically switches to a more efficient loading strategy when the number of enabled tools exceeds a configurable threshold. This helps optimize performance and reduce context usage when working with large numbers of tools.

How it works

• Default threshold: 30 tools
• Behavior: When the number of enabled tools exceeds the threshold, the server switches to dynamic tool loading

Configuration

You can configure the dynamic tool loading threshold in two ways:

Command Line Argument

npx -y @commercetools/mcp-essentials --tools=all --dynamicToolLoadingThreshold=50 --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Environment Variable

export DYNAMIC_TOOL_LOADING_THRESHOLD=50
npx -y @commercetools/mcp-essentials --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL

Example with Claude Desktop

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": [
        "-y",
        "@commercetools/mcp-essentials@latest",
        "--tools=all",
        "--clientId=CLIENT_ID",
        "--clientSecret=CLIENT_SECRET",
        "--authUrl=AUTH_URL",
        "--projectKey=PROJECT_KEY",
        "--apiUrl=API_URL",
        "--dynamicToolLoadingThreshold=25"
      ]
    }
  }
}

MCP Essentials

The commercetools MCP Essentials enables popular agent frameworks including LangChain, Vercel's AI SDK, and Model Context Protocol (MCP) to integrate with APIs through function calling. The library is not exhaustive of the entire commercetools API. It includes support for TypeScript and is built directly on top of the [Node][node-sdk] SDK.

Included below are basic instructions, but refer to the TypeScript package for more information.

TypeScript

Installation

You don't need this source code unless you want to modify the package. If you just want to use the package run:

npm install @commercetools/agent-essentials

Requirements

• Node 18+

Usage

The library needs to be configured with your commercetools project credentials which are available in your Merchant center. Important: Ensure that the API client credentials have the necessary scopes aligned with the actions you configure in the agent essentials. For example, if you configure products: { read: true }, your API client must have the view_products scope. Additionally, configuration enables you to specify the types of actions that can be taken using the agent essentials.

Client Credentials Authentication (Default)

import { CommercetoolsAgentEssentials } from "@commercetools/agent-essentials/langchain";

const commercetoolsAgentEssentials = await CommercetoolsAgentEssentials.create({
  authConfig: {
    type: 'client_credentials',
    clientId: process.env.CLIENT_ID!,,
    clientSecret: process.env.CLIENT_SECRET!,,
    projectKey: process.env.PROJECT_KEY!,
    authUrl: process.env.AUTH_URL!,
    apiUrl: process.env.API_URL!,
  },
  configuration: {
    actions: {
      products: {
        read: true,
        create: true,
        update: true,
      },
      project: {
        read: true,
      },
    },
  },
});

Access Token Authentication

import { CommercetoolsAgentEssentials } from "@commercetools/agent-essentials/langchain";

const commercetoolsAgentEssentials = await CommercetoolsAgentEssentials.create({
  authConfig: {
    type: "auth_token",
    accessToken: process.env.ACCESS_TOKEN!,
    projectKey: process.env.PROJECT_KEY!,
    authUrl: process.env.AUTH_URL!,
    apiUrl: process.env.API_URL!,
  },
  configuration: {
    actions: {
      products: {
        read: true,
        create: true,
        update: true,
      },
      project: {
        read: true,
      },
    },
  },
});

Tools

The agent essentials work with LangChain and Vercel's AI SDK and can be passed as a list of tools. For example:

import { AgentExecutor, createStructuredChatAgent } from "langchain/agents";

const tools = commercetoolsAgentEssentials.getTools();

const agent = await createStructuredChatAgent({
  llm,
  tools,
  prompt,
});

const agentExecutor = new AgentExecutor({
  agent,
  tools,
});

Model Context Protocol

The commercetools MCP Essentials also supports setting up your own MCP server. For example:

import { CommercetoolsAgentEssentials } from "@commercetools/agent-essentials/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await CommercetoolsAgentEssentials.create({
  authConfig: {
    type: 'client_credentials',
    clientId: process.env.CLIENT_ID!,,
    clientSecret: process.env.CLIENT_SECRET!,,
    projectKey: process.env.PROJECT_KEY!,
    authUrl: process.env.AUTH_URL!,
    apiUrl: process.env.API_URL!,
  },
  configuration: {
    actions: {
      products: {
        read: true,
      },
      cart: {
        read: true,
        create: true,
        update: true,
      },
    },
  },
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("My custom commercetools MCP Server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

getTools()

Returns the current set of available tools that can be used with LangChain, AI SDK, or other agent frameworks:

const tools = commercetoolsAgentEssentials.getTools();

Custom Tools

The self managed @commercetools/agent-essentials includes supports for custom tools. A list of custom tools implementations can be passed over and registered at runtime by the bootstrapping MCP server. This is especially useful when the intended tool is not yet implemented into the MCP essentials or to give users complete control and customization of their tools behaviour and how it interact with the underlying LLM.

usage

import { CommercetoolsAgentEssentials } from "@commercetools/agent-essentials/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await CommercetoolsAgentEssentials.create({
  authConfig: {...},
  configuration: {
    customTools: [
      {
        name: "Get Project",
        method: "get_project",
        description: `This tool will fetch information about a commercetools project.\n\n
           This tool will accept a project and fetch information about the provided key. \n\n
          `, // It is important that this description is well details and explicitly descripts what this tool does and the paramenters it receieves/
        parameters: z.object({
          projectKey: z
            .string()
            .optional()
            .describe(
              "The key of the project to read. If not provided, the current project will be used."
            ),
        }),
        actions: {},
        execute: async (args: { projectKey: string }, api: ApiRoot) => {
          // already existing functions can be used here e.g const response = await import('ctService').getProject('demo-project-key-a7fc1182');
          const response = await api.withProjectKey(args).get().execute();
          return JSON.stringify(response);
        },
      },
      ...
    ],
    actions: {...},
  },
});
...

Streamable HTTP MCP server

As of version v2.0.0 of the @commercetools/mcp-essentials MCP server now supports Streamable HTTP (remote) server.

npx -y @commercetools/mcp-essentials \
  --tools=all \
  --authType=client_credentials \
  --clientId=CLIENT_ID \
  --clientSecret=CLIENT_SECRET \
  --projectKey=PROJECT_KEY \
  --authUrl=AUTH_URL \
  --apiUrl=API_URL \
  --remote=true \
  --stateless=true \
  --port=8888

You can connect to the running remote server using Claude by specifying the below in the claude_desktop_config.json file.

{
  "mcpServers": {
    "commercetools": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8888/mcp", "..."]
    }
  }
}

You can also use the Streamable HTTP server with the Agent Essentials like an SDK and develop on it.

import express from "express";
import {
  CommercetoolsAgentEssentials,
  CommercetoolsAgentEssentialsStreamable,
} from "@commercetools/agent-essentials/modelcontextprotocol";

const expressApp = express();

const getAgentServer = async () => {
  return CommercetoolsAgentEssentials.create({
    authConfig: {
      type: "client_credentials",
      clientId: process.env.CLIENT_ID!,
      clientSecret: process.env.CLIENT_SECRET!,
      projectKey: process.env.PROJECT_KEY!,
      authUrl: process.env.AUTH_URL!,
      apiUrl: process.env.API_URL!,
    },
    configuration: {
      actions: {
        products: {
          read: true,
        },
        cart: {
          read: true,
          create: true,
          update: true,
        },
      },
    },
  });
};

const serverStreamable = new CommercetoolsAgentEssentialsStreamable({
  stateless: false, // make the MCP server stateless/stateful
  server: getAgentServer,
  app: expressApp, // optional express app instance
  streamableHttpOptions: {
    sessionIdGenerator: undefined,
  },
});

serverStreamable.listen(8888, function () {
  console.log("listening on 8888");
});

Without using the CommercetoolsAgentEssentials, you can directly use only the CommercetoolsAgentEssentialsStreamable class and the agent server will be bootstrapped internally.

import { CommercetoolsAgentEssentialsStreamable } from "@commercetools/agent-essentials/modelcontextprotocol";
import express from "express";

const expressApp = express();

const server = new CommercetoolsAgentEssentialsStreamable({
  authConfig: {
    type: "client_credentials",
    clientId: process.env.CLIENT_ID!,
    clientSecret: process.env.CLIENT_SECRET!,
    projectKey: process.env.PROJECT_KEY!,
    authUrl: process.env.AUTH_URL!,
    apiUrl: process.env.API_URL!,
  },
  configuration: {
    actions: {
      project: {
        read: true,
      },
      // other tools can go here
    },
  },

  stateless: false,
  app: expressApp,
  streamableHttpOptions: {
    sessionIdGenerator: undefined,
  },
});

server.listen(8888, function () {
  console.log("listening on 8888");
});