Hybris MCP

🚀 Hybris MCP Server

The MCP (Model Context Protocol) server is designed for integrating with SAP Commerce Cloud (Hybris). It enables AI assistants like Claude to interact with your Hybris instance.

🚀 Quick Start

The Hybris MCP Server allows AI assistants such as Claude to interact with your Hybris instance. Follow the steps below to get started.

✨ Features

• Product Management: Search for products, retrieve product details, and browse product categories.
• Order Management: View orders and their detailed information.
• FlexibleSearch: Directly execute FlexibleSearch queries.
• Groovy Scripts: Run Groovy scripts through the scripting console.
• ImpEx: Import and export data in ImpEx format.
• Cron Jobs: List and trigger cron jobs.
• Cache Management: Clear Hybris caches.
• Catalog Sync: Trigger catalog synchronization.
• Health Checks: Monitor the system's health.

📦 Installation

git clone <repository-url>
cd hybris-mcp
npm install
npm run build

📚 Documentation

Configuration

Configure the server using environment variables:

Common Configurations

Standard Hybris (localhost):

HYBRIS_BASE_URL=https://localhost:9002
HYBRIS_USERNAME=admin
HYBRIS_PASSWORD=nimda

SAP Commerce Cloud (CCv2):

HYBRIS_BASE_URL=https://backoffice.your-environment.model-t.cc.commerce.ondemand.com
HYBRIS_USERNAME=admin
HYBRIS_PASSWORD=your-password
HYBRIS_HAC_PATH=/hac

Custom Site Configuration:

HYBRIS_BASE_URL=https://localhost:9002
HYBRIS_USERNAME=admin
HYBRIS_PASSWORD=nimda
HYBRIS_BASE_SITE_ID=yoursite
HYBRIS_CATALOG_ID=yourProductCatalog
HYBRIS_CATALOG_VERSION=Online

Usage with Claude Code

Add the MCP server using the CLI:

claude mcp add hybris \
  -e HYBRIS_BASE_URL=https://localhost:9002 \
  -e HYBRIS_USERNAME=admin \
  -e HYBRIS_PASSWORD=nimda \
  -- node /path/to/hybris-mcp/dist/index.js

Or manually add it to your Claude Code MCP settings (~/.claude.json or project config):

{
  "mcpServers": {
    "hybris": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/hybris-mcp/dist/index.js"],
      "env": {
        "HYBRIS_BASE_URL": "https://localhost:9002",
        "HYBRIS_USERNAME": "admin",
        "HYBRIS_PASSWORD": "nimda"
      }
    }
  }
}

Usage with Claude Desktop

Add it to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "hybris": {
      "command": "node",
      "args": ["/path/to/hybris-mcp/dist/index.js"],
      "env": {
        "HYBRIS_BASE_URL": "https://localhost:9002",
        "HYBRIS_USERNAME": "admin",
        "HYBRIS_PASSWORD": "nimda"
      }
    }
  }
}

Available Tools

Product & Catalog (OCC API)

Orders (OCC API)

Administration (HAC)

Example Prompts

Search Products

Search for "camera" products in Hybris

FlexibleSearch

Run a FlexibleSearch query: SELECT {pk}, {code}, {name[en]} FROM {Product} WHERE {code} LIKE '%camera%'

Execute Groovy

Execute this Groovy script to count products:
import de.hybris.platform.core.Registry
def ctx = Registry.getApplicationContext()
def flexibleSearchService = ctx.getBean("flexibleSearchService")
def query = "SELECT COUNT(*) FROM {Product}"
def result = flexibleSearchService.search(query)
println "Total products: ${result.result[0]}"

Import ImpEx

Import this ImpEx to create a product:
INSERT_UPDATE Product; code[unique=true]; name[lang=en]; catalogVersion(catalog(id),version)
; testProduct001 ; Test Product ; electronicsProductCatalog:Online

Trigger Catalog Sync

Sync the electronics catalog from Staged to Online

Security Notes

• Store your credentials securely and never commit them to version control.
• Use environment variables or secure secret management.
• The server requires HAC admin access for administrative tools.
• Consider using read - only credentials if you only need OCC API access.

Development

# Watch mode for development
npm run dev

# Build
npm run build

# Run directly
HYBRIS_BASE_URL=https://localhost:9002 \
HYBRIS_USERNAME=admin \
HYBRIS_PASSWORD=nimda \
npm start

Troubleshooting

Connection Issues

1. Verify that your Hybris instance is running and accessible.
2. Check if HAC is enabled and accessible at the configured path.
3. Ensure that your credentials have admin access to HAC.

SSL Certificate Errors

For local development with self - signed certificates:

NODE_TLS_REJECT_UNAUTHORIZED=0 node dist/index.js

CSRF Token Errors

The server handles CSRF tokens automatically. If you encounter CSRF errors:

1. Check that HAC login works manually.
2. Verify that the HAC path is correct.
3. Try restarting the MCP server to get a fresh session.

📄 License

This project is licensed under the MIT license.