UnoPim MCP Server 🚀

A powerful Model Context Protocol (MCP) server that enables Claude Desktop to manage your UnoPim Product Information Management system. Create products, manage attributes, upload media, and handle complex configurable products - all through natural language conversations with Claude.

✨ Features

• 🔌 Full UnoPim API Integration - Create and manage attributes, families, categories, and products
• 👕 Configurable Products - Full support for products with variants (e.g., T-shirts with color/size options)
• 📸 Media Upload - Upload product images and category media via URL or base64
• 🧠 Smart Product Creation - Automatically validates against family schema before creating
• 🌐 HTTP/SSE Transport - Expose via ngrok for Claude Desktop remote access
• 🔄 Automatic Token Refresh - OAuth2 with automatic token management

🚀 Quick Start

1. Install dependencies

npm install
npm run build

2. Configure environment

export UNOPIM_BASE_URL="http://your-unopim:8000"
export UNOPIM_CLIENT_ID="your_client_id"
export UNOPIM_CLIENT_SECRET="your_client_secret"
export UNOPIM_USERNAME="api-user@email.com"
export UNOPIM_PASSWORD="password"

3. Start the server

# HTTP mode (recommended for Claude Desktop)
node dist/index-http.js

4. Expose via ngrok (for remote access)

ngrok http 3000

📋 Claude Desktop Configuration

Remote (HTTP/SSE) mode via ngrok ⭐ Recommended

{
  "mcpServers": {
    "unopim": {
      "url": "https://your-ngrok-url.ngrok-free.app/sse"
    }
  }
}

Local (stdio) mode

{
  "mcpServers": {
    "unopim": {
      "command": "node",
      "args": ["/path/to/unopim-mcp/dist/index.js"],
      "env": {
        "UNOPIM_BASE_URL": "https://your-unopim.com",
        "UNOPIM_CLIENT_ID": "your_client_id",
        "UNOPIM_CLIENT_SECRET": "your_client_secret",
        "UNOPIM_USERNAME": "api-user",
        "UNOPIM_PASSWORD": "password"
      }
    }
  }
}

🛠️ Available Tools (24 tools)

Schema & Discovery

Attribute Management

Family Management

Category Management

Product Management

Configurable Products

Media Upload ⭐ Automatic Linking

Note: Media upload tools now automatically update the product/category with the uploaded file path. Images are immediately visible in UnoPim UI after upload!

👕 Configurable Products Workflow

Creating a configurable product (e.g., T-shirt with color variants):

Step 1: Create the configurable product (parent)

{
  "sku": "tshirt-config-001",
  "family": "default",
  "super_attributes": ["color"],
  "values": {
    "common": { "sku": "tshirt-config-001" },
    "channel_locale_specific": {
      "default": {
        "en_US": { "name": "T-Shirt Configurable" }
      }
    },
    "categories": [],
    "associations": { "up_sells": [], "cross_sells": [], "related_products": [] }
  }
}

Step 2: Add variants (one at a time)

{
  "parent": "tshirt-config-001",
  "family": "default",
  "sku": "tshirt-red-001",
  "values": {
    "common": { "sku": "tshirt-red-001", "color": "Red" },
    "channel_locale_specific": {
      "default": {
        "en_US": { "name": "T-Shirt Red" }
      }
    },
    "categories": []
  },
  "variant_attributes": { "color": "Red" }
}

Step 3: Add product image

{
  "sku": "tshirt-red-001",
  "attribute": "image",
  "file_url": "https://example.com/tshirt-red.jpg"
}

📸 Media Upload

Upload product images via URL or base64 - images are automatically linked to the product:

// Via URL
{
  "sku": "PROD001",
  "attribute": "image",
  "file_url": "https://example.com/product.jpg"
}

// Via Base64
{
  "sku": "PROD001",
  "attribute": "image",
  "file_base64": "iVBORw0KGgo...",
  "filename": "product-image.jpg"
}

What happens automatically:

1. ✅ File uploads to UnoPim storage
2. ✅ Attribute metadata fetched to determine scope (common/locale_specific/channel_specific/channel_locale_specific)
3. ✅ Product updated with file path in correct value structure
4. ✅ Image immediately visible in UnoPim UI

No manual product update needed - the tool handles everything!

⚠️ Important API Notes

Attribute Value Structure

UnoPim attributes have different scoping based on value_per_locale and value_per_channel:

Example: The name attribute typically requires channel_locale_specific:

{
  "values": {
    "common": { "sku": "PROD001" },
    "channel_locale_specific": {
      "default": {
        "en_US": { "name": "Product Name" }
      }
    }
  }
}

🐛 Known API Quirks

🔧 Development

# Build
npm run build

# Watch mode
npm run watch

# Type check
npm run typecheck

# Test with MCP Inspector
npx @modelcontextprotocol/inspector dist/index.js

📊 Environment Variables

Required

Optional

🏗️ Architecture

┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
│  Claude Desktop │────▶│   ngrok      │────▶│  MCP Server │
│                 │ SSE │              │     │  (Node.js)  │
└─────────────────┘     └──────────────┘     └──────┬──────┘
                                                     │
                                                     │ OAuth2
                                                     │ REST API
                                                     ▼
                                              ┌─────────────┐
                                              │   UnoPim    │
                                              │    PIM      │
                                              └─────────────┘

📁 Project Structure

src/
├── index-http.ts      # HTTP server with SSE (for ngrok)
├── index.ts           # stdio server (for local)
├── config.ts          # Configuration loader
├── auth/
│   └── oauth.ts       # OAuth2 token management
├── client/
│   └── unopim-client.ts  # HTTP client with retry logic
├── tools/
│   ├── attributes.ts  # Attribute CRUD
│   ├── categories.ts  # Category management
│   ├── families.ts    # Family management
│   ├── groups.ts      # Attribute groups
│   ├── products.ts    # Product CRUD + media upload
│   └── schema.ts      # Schema discovery
└── types/
    ├── errors.ts      # Error handling
    ├── oauth.ts       # OAuth types
    └── unopim.ts      # API types

🎉 Example Conversation with Claude

You: Create a T-shirt product family with name, description, price and color attributes

Claude: I'll create the family with those attributes... (Uses unopim_create_family, unopim_create_attribute, etc.)

You: Now create a configurable T-shirt with red, blue and green variants at $29.99

Claude: I'll create the configurable product and add the color variants... (Uses unopim_create_configurable_product, unopim_add_variant)

You: Upload this image for the red variant: https://example.com/red-shirt.jpg

Claude: Uploading the image to the red variant... (Uses unopim_upload_product_media)

📄 License

ISC

🙏 Credits

Built with:

• Model Context Protocol SDK
• UnoPim PIM
• TypeScript

Made with ❤️ for seamless PIM management through AI