Catalog Services Server

An MCP (Model Context Protocol) server for Adobe Commerce Catalog Services, providing tools to interact with product, category, and environment services via gRPC and REST APIs.

Proto Schemas from https://git.corp.adobe.com/magento/proto-schemas

Features

This MCP server provides the following tools:

• Product Variants: Get product variant information (configurable product options)
• Product Overrides: Query product price overrides by customer group and website
• Category Permissions: Retrieve category permission information
• Environment Details: Get environment, website, and store view information

Prerequisites

• Python 3.11 or higher
• uv - Fast Python package installer and resolver
• Cursor IDE (or any MCP-compatible client)

Installation

1. Install uv

If you don't have uv installed, install it first:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

2. Clone and Setup the Project

# Clone the repository
git clone <repository-url>
cd catalog-services-mcp

# Install dependencies using uv
uv sync

3. Configure Environment Variables

Set the required environment variables for authentication:

# Adobe Commerce Catalog Service credentials
export CATALOG_SERVICE_API_KEY="your_api_key"
export CATALOG_SERVICE_PRIVATE_KEY="your_private_key"

# New Relic credentials (if using New Relic tools)
export NEW_RELIC_API_KEY="your_new_relic_api_key"

4. Configure MCP in Cursor

Add the following configuration to your Cursor MCP settings file (~/.cursor/mcp.json):

{
  "mcpServers": {
    "Catalog Services": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/YOUR_USERNAME/path/to/catalog-services-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

Important: Replace /Users/YOUR_USERNAME/path/to/catalog-services-mcp with the actual path to your cloned repository.

5. Restart Cursor

After adding the configuration, restart Cursor IDE to load the MCP server.

Usage

Once configured, you can use the Catalog Services tools in Cursor by invoking them through the MCP protocol. Available tools include:

• get_product_variants - Retrieve product variant information
• get_product_overrides_by_website - Get product price overrides for all customer groups
• get_category_permissions - Query category permissions
• get_environment_details - Get environment information
• get_environment_store_views - List all store views for an environment
• find_store_view_codes - Find store views by website/store code

Development

Project Structure

catalog-services-mcp/
├── catalog_service/          # Main service module
│   ├── generated/           # Generated protobuf files
│   ├── proto-schemas/       # Proto schema definitions
│   ├── product_service_tool.py
│   ├── product_override_service_tool.py
│   ├── variant_service_tool.py
│   ├── category_permission_service_tool.py
│   └── environment_service_tool.py
├── main.py                  # MCP server entry point
├── pyproject.toml          # Project dependencies
└── README.md

Regenerating Protobuf Files

If you need to regenerate the protobuf files from the proto schemas:

cd catalog_service
./generate_protos.sh

Troubleshooting

MCP Server Not Starting

1. Check that uv is installed and in your PATH:

   which uv
   

2. Verify the path in mcp.json is correct and absolute

3. Check Cursor logs for error messages

Authentication Errors

Ensure your environment variables are set correctly:

echo $CATALOG_SERVICE_API_KEY
echo $CATALOG_SERVICE_PRIVATE_KEY

Connection Issues

• Verify network connectivity to Adobe Commerce services
• Check that you're connected to the corporate VPN if required
• Ensure firewall rules allow outbound connections

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

Internal Adobe Commerce project