{"id":30157454,"url":"https://github.com/commercetools/mcp-essentials","last_synced_at":"2025-08-11T13:39:03.177Z","repository":{"id":300930753,"uuid":"1007084529","full_name":"commercetools/mcp-essentials","owner":"commercetools","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-05T09:00:56.000Z","size":639,"stargazers_count":5,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-05T11:15:08.614Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/commercetools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-23T12:45:46.000Z","updated_at":"2025-08-01T11:32:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"a97a3298-0bc4-41aa-9adc-f8a6839ea681","html_url":"https://github.com/commercetools/mcp-essentials","commit_stats":null,"previous_names":["commercetools/mcp-essentials"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/commercetools/mcp-essentials","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fmcp-essentials","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fmcp-essentials/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fmcp-essentials/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fmcp-essentials/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/commercetools","download_url":"https://codeload.github.com/commercetools/mcp-essentials/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commercetools%2Fmcp-essentials/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269899084,"owners_count":24493073,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-11T13:39:02.510Z","updated_at":"2025-08-11T13:39:03.166Z","avatar_url":"https://github.com/commercetools.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!IMPORTANT]\n\u003e 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.\n\n# commercetools MCP Essentials\n\nThis 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.\n\n# commercetools Model Context Protocol\n\n## Setup\n\nTo run the commercetools MCP server using npx, use the following command:\n\n### Client Credentials Authentication (Default)\n\n```bash\n# To set up all available tools (authType is optional, defaults to client_credentials)\nnpx -y @commercetools/mcp-essentials --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL\n\n# Explicitly specify client_credentials (optional)\nnpx -y @commercetools/mcp-essentials --tools=all --authType=client_credentials --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL\n\n# To set up all read-only tools\nnpx -y @commercetools/mcp-essentials --tools=all.read --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL\n\n```\n\n```bash\n# To set up specific tools\nnpx -y @commercetools/mcp-essentials --tools=products.read,products.create --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL\n```\n\n### Access Token Authentication\n\n```bash\n# To set up all available tools with access token\nnpx -y @commercetools/mcp-essentials --tools=all --authType=auth_token --accessToken=ACCESS_TOKEN --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL\n\n# To set up all read-only tools with access token\nnpx -y @commercetools/mcp-essentials --tools=all.read --authType=auth_token --accessToken=ACCESS_TOKEN --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL\n```\n\nMake 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.\n\n### Authentication Options\n\nThe MCP server supports two authentication methods:\n\n| Authentication Type | Required Arguments | Description |\n|-------------------|-------------------|-------------|\n| `client_credentials` (default) | `--clientId`, `--clientSecret` | Uses API client credentials for authentication. `--authType=client_credentials` is optional since this is the default |\n| `auth_token` | `--accessToken` | Uses a pre-existing access token for authentication. Requires `--authType=auth_token` |\n\n### Usage with Claude Desktop\n\nAdd the following to your `claude_desktop_config.json`. See [here](https://modelcontextprotocol.io/quickstart/user) for more details.\n\n#### Client Credentials Authentication\n\n```json\n{\n  \"mcpServers\": {\n    \"commercetools\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@commercetools/mcp-essentials@latest\",\n        \"--tools=all\",\n        \"--clientId=CLIENT_ID\",\n        \"--clientSecret=CLIENT_SECRET\",\n        \"--authUrl=AUTH_URL\",\n        \"--projectKey=PROJECT_KEY\",\n        \"--apiUrl=API_URL\"\n      ]\n    }\n  }\n}\n```\n\n**Note**: You can optionally add `\"--authType=client_credentials\"` to be explicit, but it's not required since this is the default.\n\n#### Access Token Authentication\n\n```json\n{\n  \"mcpServers\": {\n    \"commercetools\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@commercetools/mcp-essentials@latest\",\n        \"--tools=all\",\n        \"--authType=auth_token\",\n        \"--accessToken=ACCESS_TOKEN\",\n        \"--authUrl=AUTH_URL\",\n        \"--projectKey=PROJECT_KEY\",\n        \"--apiUrl=API_URL\"\n      ]\n    }\n  }\n}\n```\n\n**Alternative: To use only read-only tools, replace `\"--tools=all\"` with `\"--tools=all.read\"`**\n\n## Available tools\n\n### Special Tool Options\n\n| Tool       | Description                                                      |\n| ---------- | ---------------------------------------------------------------- |\n| `all`      | Enable all available tools (read, create, and update operations) |\n| `all.read` | Enable all read-only tools (safe for read-only access)           |\n\n### Individual Tools\n\n| Tool                       | Description                                                                                                          |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| `products.read`            | [Read product information](https://docs.commercetools.com/api/projects/products#query-products)                      |\n| `products.create`          | [Create product information](https://docs.commercetools.com/api/projects/products#create-product)                    |\n| `products.update`          | [Update product information](https://docs.commercetools.com/api/projects/products#update-product)                    |\n| `project.read`             | [Read project information](https://docs.commercetools.com/api/projects/project#get-project)                          |\n| `product-search.read`      | [Search products](https://docs.commercetools.com/api/projects/products#search-products)                              |\n| `category.read`            | [Read category information](https://docs.commercetools.com/api/projects/categories#get-category-by-id)               |\n| `category.create`          | [Create category](https://docs.commercetools.com/api/projects/categories#create-category)                            |\n| `category.update`          | [Update category](https://docs.commercetools.com/api/projects/categories#update-category)                            |\n| `channel.read`             | [Read channel information](https://docs.commercetools.com/api/projects/channels#query-channels)                      |\n| `channel.create`           | [Create channel](https://docs.commercetools.com/api/projects/channels#create-channel)                                |\n| `channel.update`           | [Update channel information](https://docs.commercetools.com/api/projects/channels#update-channel)                    |\n| `product-selection.read`   | [Read product selection](https://docs.commercetools.com/api/projects/product-selections#get-productselection-by-id)  |\n| `product-selection.create` | [Create product selection](https://docs.commercetools.com/api/projects/product-selections#create-a-productselection) |\n| `product-selection.update` | [Update product selection](https://docs.commercetools.com/api/projects/product-selections#update-productselection)   |\n| `order.read`               | [Read order information](https://docs.commercetools.com/api/projects/orders#get-order-by-id)                         |\n| `order.create`             | [Create order](https://docs.commercetools.com/api/projects/orders#create-order-from-cart) (from cart, quote, import) |\n| `order.update`             | [Update order information](https://docs.commercetools.com/api/projects/orders#update-order)                          |\n| `cart.read`                | [Read cart information](https://docs.commercetools.com/api/projects/carts#get-cart-by-id)                            |\n| `cart.create`              | [Create cart](https://docs.commercetools.com/api/projects/carts#create-cart)                                         |\n| `cart.update`              | [Update cart information](https://docs.commercetools.com/api/projects/carts#update-cart)                             |\n| `customer.read`            | [Read customer information](https://docs.commercetools.com/api/projects/customers#query-customers)                   |\n| `customer.create`          | [Create customer](https://docs.commercetools.com/api/projects/customers#create-customer)                             |\n| `customer.update`          | [Update customer information](https://docs.commercetools.com/api/projects/customers#update-customer)                 |\n| `customer-group.read`      | [Read customer group](https://docs.commercetools.com/api/projects/customerGroups#get-customergroup)                  |\n| `customer-group.create`    | [Create customer group](https://docs.commercetools.com/api/projects/customerGroups#create-customergroup)             |\n| `customer-group.update`    | [Update customer group](https://docs.commercetools.com/api/projects/customerGroups#update-customergroup)             |\n| `quote.read`               | [Read quote information](https://docs.commercetools.com/api/projects/quotes#get-quote-by-id)                         |\n| `quote.create`             | [Create quote](https://docs.commercetools.com/api/projects/quotes#create-quote-from-staged-quote)                    |\n| `quote.update`             | [Update quote information](https://docs.commercetools.com/api/projects/quotes#update-quote)                          |\n| `quote-request.read`       | [Read quote request](https://docs.commercetools.com/api/projects/quote-requests#get-quoterequest-by-id)              |\n| `quote-request.create`     | [Create quote request](https://docs.commercetools.com/api/projects/quote-requests#create-quoterequest)               |\n| `quote-request.update`     | [Update quote request](https://docs.commercetools.com/api/projects/quote-requests#update-quoterequest)               |\n| `staged-quote.read`        | [Read staged quote](https://docs.commercetools.com/api/projects/staged-quotes#get-stagedquote-by-id)                 |\n| `staged-quote.create`      | [Create staged quote](https://docs.commercetools.com/api/projects/staged-quotes#create-stagedquote)                  |\n| `staged-quote.update`      | [Update staged quote](https://docs.commercetools.com/api/projects/staged-quotes#update-stagedquote)                  |\n| `standalone-price.read`    | [Read standalone price](https://docs.commercetools.com/api/projects/standalone-prices#get-standaloneprice-by-id)     |\n| `standalone-price.create`  | [Create standalone price](https://docs.commercetools.com/api/projects/standalone-prices#create-standaloneprice)      |\n| `standalone-price.update`  | [Update standalone price](https://docs.commercetools.com/api/projects/standalone-prices#update-standaloneprice)      |\n| `product-discount.read`    | [Read product discount](https://docs.commercetools.com/api/projects/productDiscounts#get-productdiscount-by-id)      |\n| `product-discount.create`  | [Create product discount](https://docs.commercetools.com/api/projects/productDiscounts#create-productdiscount)       |\n| `product-discount.update`  | [Update product discount](https://docs.commercetools.com/api/projects/productDiscounts#update-productdiscount)       |\n| `cart-discount.read`       | [Read cart discount](https://docs.commercetools.com/api/projects/cartDiscounts#get-cartdiscount-by-id)               |\n| `cart-discount.create`     | [Create cart discount](https://docs.commercetools.com/api/projects/cartDiscounts#create-cartdiscount)                |\n| `cart-discount.update`     | [Update cart discount](https://docs.commercetools.com/api/projects/cartDiscounts#update-cartdiscount)                |\n| `discount-code.read`       | [Read discount code information](https://docs.commercetools.com/api/projects/discount-codes#get-discountcode-by-id)  |\n| `discount-code.create`     | [Create discount code](https://docs.commercetools.com/api/projects/discount-codes#create-discountcode)               |\n| `discount-code.update`     | [Update discount code information](https://docs.commercetools.com/api/projects/discount-codes#update-discountcode)   |\n| `product-type.read`        | [Read product type](https://docs.commercetools.com/api/projects/productTypes#get-producttype-by-id)                  |\n| `product-type.create`      | [Create product type](https://docs.commercetools.com/api/projects/productTypes#create-producttype)                   |\n| `product-type.update`      | [Update product type](https://docs.commercetools.com/api/projects/productTypes#update-producttype)                   |\n| `bulk.create`              | Create entities in bulk                                                                                              |\n| `bulk.update`              | Update entities in bulk                                                                                              |\n| `inventory.read`           | [Read inventory information](https://docs.commercetools.com/api/projects/inventory#get-inventoryentry-by-id)         |\n| `inventory.create`         | [Create inventory](https://docs.commercetools.com/api/projects/inventory#create-inventoryentry)                      |\n| `inventory.update`         | [Update inventory information](https://docs.commercetools.com/api/projects/inventory#update-inventoryentry)          |\n| `store.read`               | [Read store](https://docs.commercetools.com/api/projects/stores#get-store-by-id)                                     |\n| `store.create`             | [Create store](https://docs.commercetools.com/api/projects/stores#create-store)                                      |\n| `store.update`             | [Update store](https://docs.commercetools.com/api/projects/stores#update-store)                                      |\n| `business-unit.read`       | [Read business unit](https://docs.commercetools.com/api/projects/business-units#get-businessunit-by-id)              |\n| `business-unit.create`     | [Create business unit](https://docs.commercetools.com/api/projects/business-units#create-businessunit)               |\n| `business-unit.update`     | [Update business unit](https://docs.commercetools.com/api/projects/business-units#update-businessunit)               |\n\nTo view information on how to develop the MCP server, see [this README](/modelcontextprotocol/README.md).\n\n# MCP Essentials\n\nThe 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.\n\nIncluded below are basic instructions, but refer to the [TypeScript](/typescript) package for more information.\n\n## TypeScript\n\n### Installation\n\nYou don't need this source code unless you want to modify the package. If you just\nwant to use the package run:\n\n```\nnpm install @commercetools/agent-essentials\n```\n\n#### Requirements\n\n- Node 18+\n\n### Usage\n\nThe library needs to be configured with your commercetools project credentials which are available in your [Merchant center](https://docs.commercetools.com/getting-started/create-api-client).\n**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.\nAdditionally, `configuration` enables you to specify the types of actions that can be taken using the agent essentials.\n\n### Client Credentials Authentication (Default)\n\n```typescript\nimport { CommercetoolsAgentEssentials } from \"@commercetools/agent-essentials/langchain\";\n\nconst commercetoolsAgentEssentials = new CommercetoolsAgentEssentials({\n  authConfig: {\n    type: 'client_credentials',\n    clientId: process.env.CLIENT_ID!,,\n    clientSecret: process.env.CLIENT_SECRET!,,\n    projectKey: process.env.PROJECT_KEY!,\n    authUrl: process.env.AUTH_URL!,\n    apiUrl: process.env.API_URL!,\n  },\n  configuration: {\n    actions: {\n      products: {\n        read: true,\n        create: true,\n        update: true,\n      },\n      project: {\n        read: true,\n      },\n    },\n  },\n});\n```\n\n### Access Token Authentication\n\n```typescript\nimport { CommercetoolsAgentEssentials } from \"@commercetools/agent-essentials/langchain\";\n\nconst commercetoolsAgentEssentials = new CommercetoolsAgentEssentials({\n  authConfig: {\n    type: 'auth_token',\n    accessToken: process.env.ACCESS_TOKEN!,\n    projectKey: process.env.PROJECT_KEY!,\n    authUrl: process.env.AUTH_URL!,\n    apiUrl: process.env.API_URL!,\n  },\n  configuration: {\n    actions: {\n      products: {\n        read: true,\n        create: true,\n        update: true,\n      },\n      project: {\n        read: true,\n      },\n    },\n  },\n});\n```\n\n#### Tools\n\nThe agent essentials work with LangChain and Vercel's AI SDK and can be passed as a list of tools. For example:\n\n```typescript\nimport { AgentExecutor, createStructuredChatAgent } from \"langchain/agents\";\n\nconst tools = commercetoolsAgentEssentials.getTools();\n\nconst agent = await createStructuredChatAgent({\n  llm,\n  tools,\n  prompt,\n});\n\nconst agentExecutor = new AgentExecutor({\n  agent,\n  tools,\n});\n```\n\n## Model Context Protocol\n\nThe commercetools MCP Essentials also supports setting up your own MCP server. For example:\n\n```typescript\nimport { CommercetoolsAgentEssentials } from \"@commercetools/agent-essentials/modelcontextprotocol\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\n\nconst server = new CommercetoolsAgentEssentials({\n  authConfig: {\n    type: 'client_credentials',\n    clientId: process.env.CLIENT_ID!,,\n    clientSecret: process.env.CLIENT_SECRET!,,\n    projectKey: process.env.PROJECT_KEY!,\n    authUrl: process.env.AUTH_URL!,\n    apiUrl: process.env.API_URL!,\n  },\n  configuration: {\n    actions: {\n      products: {\n        read: true,\n      },\n      cart: {\n        read: true,\n        create: true,\n        update: true,\n      },\n    },\n  },\n});\n\nasync function main() {\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n  console.error(\"My custom commercetools MCP Server running on stdio\");\n}\n\nmain().catch((error) =\u003e {\n  console.error(\"Fatal error in main():\", error);\n  process.exit(1);\n});\n```\n\n#### getTools()\n\nReturns the current set of available tools that can be used with LangChain, AI SDK, or other agent frameworks:\n\n```typescript\nconst tools = commercetoolsAgentEssentials.getTools();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercetools%2Fmcp-essentials","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommercetools%2Fmcp-essentials","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommercetools%2Fmcp-essentials/lists"}