Hybris MCP Server

MCP (Model Context Protocol) server for SAP Commerce Cloud (Hybris) integration. This server allows AI assistants like Claude to interact with your Hybris instance.

Features

Product Management: Search products, get product details, browse categories
Order Management: View orders and order details
FlexibleSearch: Execute FlexibleSearch queries directly
Groovy Scripts: Run Groovy scripts via the scripting console
ImpEx: Import and export data using ImpEx format
Cron Jobs: List and trigger cron jobs
Cache Management: Clear Hybris caches
Catalog Sync: Trigger catalog synchronization
Health Checks: Monitor system health

Installation

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

Configuration

Configure via environment variables:

Variable	Required	Description	Default
`HYBRIS_BASE_URL`	Yes	Base URL of your Hybris instance	-
`HYBRIS_USERNAME`	Yes	Admin username (HAC access required)	-
`HYBRIS_PASSWORD`	Yes	Admin password	-
`HYBRIS_BASE_SITE_ID`	No	OCC base site ID	`electronics`
`HYBRIS_CATALOG_ID`	No	Product catalog ID	`electronicsProductCatalog`
`HYBRIS_CATALOG_VERSION`	No	Catalog version	`Online`
`HYBRIS_HAC_PATH`	No	HAC path prefix	`/hac`

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

Usage with Cursor

Add to your Cursor MCP configuration (~/.cursor/mcp.json):

{
  "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"
      }
    }
  }
}

Usage with Windsurf

Add to your Windsurf MCP configuration (~/.codeium/windsurf/mcp_config.json):

{
  "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"
      }
    }
  }
}

Usage with VS Code (Copilot/Continue/Cline)

For VS Code extensions that support MCP, add to your workspace .vscode/mcp.json:

{
  "servers": {
    "hybris": {
      "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 Zed

Add to your Zed settings (~/.config/zed/settings.json):

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

Usage with JetBrains IDEs

For IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs with AI Assistant, add to your MCP configuration:

macOS/Linux: ~/.config/JetBrains/mcp.json Windows: %APPDATA%\JetBrains\mcp.json

{
  "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"
      }
    }
  }
}

Usage with Sourcegraph Cody

Add to your Cody MCP configuration (~/.config/cody/mcp.json):

{
  "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"
      }
    }
  }
}

Usage with Raycast

Add to your Raycast AI extension MCP settings (~/.config/raycast/mcp.json):

{
  "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"
      }
    }
  }
}

Generic MCP Configuration

For any other MCP-compatible client, the server uses stdio transport. Run with:

node /path/to/hybris-mcp/dist/index.js

Required environment variables:

HYBRIS_BASE_URL
HYBRIS_USERNAME
HYBRIS_PASSWORD

Available Tools

Administration (HAC) - Full Support

All HAC-based tools work reliably with Basic authentication:

Tool	Description
`flexible_search`	Execute FlexibleSearch queries
`execute_groovy`	Run Groovy scripts
`import_impex`	Import ImpEx data
`export_impex`	Export data to ImpEx format
`get_cronjobs`	List cron jobs and their status
`trigger_cronjob`	Trigger a cron job to run
`clear_cache`	Clear Hybris caches
`get_system_info`	Get system information
`trigger_catalog_sync`	Sync catalog versions

Product & Catalog (OCC API)

Tool	Description	Notes
`health_check`	Check system health	Always works
`get_product`	Get detailed product information by code	Works with Basic auth
`get_category`	Get category details by code	Works with Basic auth
`search_products`	Search for products in the catalog	Requires Solr indexing*
`get_categories`	List all categories in the catalog	Endpoint may not be exposed*

Orders (OCC API)

Tool	Description	Notes
`get_orders`	Get orders for a user	Requires OAuth*
`get_order`	Get specific order details	Requires OAuth*

*See Known Limitations below.

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

Known Limitations

OCC Order Endpoints Require OAuth

The get_orders and get_order tools require OAuth user authentication, not just Basic auth. These endpoints need a user-specific OAuth token obtained via the password grant flow:

POST /authorizationserver/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=user@example.com&password=secret&client_id=mobile_android&client_secret=secret

Workaround: Use flexible_search to query orders directly:

SELECT {pk}, {code}, {user}, {totalPrice} FROM {Order} WHERE {user} = ?user

Product Search Requires Solr

The search_products tool uses the OCC search endpoint which requires Solr indexing. If your instance uses a different search provider (e.g., Algolia), this endpoint may return empty results.

Workaround: Use flexible_search to query products:

SELECT {pk}, {code}, {name[en]} FROM {Product} WHERE {name[en]} LIKE '%search_term%'

Categories Endpoint May Not Be Exposed

The get_categories tool uses an OCC endpoint that may not be exposed in all Hybris configurations.

Workaround: Use flexible_search to query categories:

SELECT {pk}, {code}, {name[en]} FROM {Category} WHERE {catalogVersion} IN (
  {{ SELECT {pk} FROM {CatalogVersion} WHERE {version} = 'Online' }}
)

Security Notes

Store credentials securely - 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

Security Considerations

This MCP server provides powerful administrative access to your Hybris instance:

FlexibleSearch: Can query any data including sensitive tables (users, passwords, tokens)
Groovy Scripts: Execute arbitrary code with full system access (file system, network, processes)
ImpEx: Can modify any data in the system including user accounts and permissions

Recommendations:

Use dedicated service accounts with minimal required permissions
Enable audit logging on your Hybris instance to track all operations
Never expose the MCP server to untrusted networks or users
Review all Groovy scripts before execution in production environments
Consider network segmentation to restrict access to HAC endpoints

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

Verify your Hybris instance is running and accessible
Check if HAC is enabled and accessible at the configured path
Ensure 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

WARNING: Never use NODE_TLS_REJECT_UNAUTHORIZED=0 in production environments. This disables TLS certificate validation and exposes you to man-in-the-middle attacks. For production, configure proper SSL certificates.

CSRF Token Errors

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

Check that HAC login is working manually
Verify the HAC path is correct
Try restarting the MCP server to get a fresh session

License

MIT