UnoPim MCP Server

Version 2.0.0 -- A Model Context Protocol server that connects Claude Desktop (and other MCP clients) to a UnoPim PIM instance. Provides 35 tools for managing attributes, families, categories, products, media, and configuration.

Transports

Stdio -- Runs as a local subprocess of Claude Desktop. Requires UnoPim credentials in env vars.

HTTP -- Exposes SSE and Streamable HTTP endpoints. Intended for remote access via ngrok or cloud deployment.

Authentication

HTTP transport: OAuth browser-based (per-user)

Each user authenticates through a browser login form that Claude Desktop opens automatically (MCP OAuth spec). Uses PKCE with S256 challenge. Tokens expire after 24 hours by default (configurable via MCP_TOKEN_EXPIRY_SECONDS). Credentials are stored in localStorage for seamless re-auth.

When UNOPIM_* env vars are absent, the server runs in OAuth-only mode.

HTTP transport: API key fallback

Uses shared credentials from env vars. Set MCP_API_KEY or it defaults to UNOPIM_CLIENT_ID.

Stdio transport

Uses UNOPIM_* env vars directly. No browser-based auth.

Claude Desktop Configuration

HTTP mode with OAuth (recommended)

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

Stdio mode (local)

{
  "mcpServers": {
    "unopim": {
      "command": "node",
      "args": ["/path/to/unopim-mcp/dist/index.js"],
      "env": {
        "UNOPIM_BASE_URL": "http://your-unopim:8000",
        "UNOPIM_CLIENT_ID": "your-client-id",
        "UNOPIM_CLIENT_SECRET": "your-client-secret",
        "UNOPIM_USERNAME": "user@example.com",
        "UNOPIM_PASSWORD": "password"
      }
    }
  }
}

Tools (35)

Schema and Discovery

• unopim_get_schema -- Fetch complete data model
• unopim_get_attributes -- List all attributes with types
• unopim_get_families -- List all product families
• unopim_get_family_schema -- Get detailed schema for a specific family

Attribute Management

• unopim_create_attribute -- Create attribute (text, select, boolean, price, etc.)
• unopim_create_attribute_options -- Create options for select attributes
• unopim_get_attribute_options -- Get options for a select attribute
• unopim_get_attribute_groups -- List attribute groups
• unopim_create_attribute_group -- Create attribute group
• unopim_delete_attribute -- Delete attribute
• unopim_delete_attribute_group -- Delete attribute group

Family Management

• unopim_create_family -- Create product family
• unopim_update_family -- Update family
• unopim_delete_family -- Delete family

Category Management

• unopim_get_categories -- Fetch category tree
• unopim_create_category -- Create category
• unopim_delete_category -- Delete category
• unopim_get_category_fields -- List category fields
• unopim_create_category_field -- Create category field

Product Management

• unopim_get_products -- List products with filtering
• unopim_get_product -- Get single product by SKU
• unopim_create_product -- Create simple product
• unopim_update_product -- Update product
• unopim_upsert_product -- Create or update product
• unopim_smart_create_product -- Auto-validates against family schema before creating
• unopim_bulk_create_products -- Batch create products
• unopim_delete_product -- Delete product

Configurable Products

• unopim_create_configurable_product -- Create parent product with variants
• unopim_add_variant -- Add variant to configurable product
• unopim_update_configurable_product -- Update configurable product

Media Upload

• unopim_upload_product_media -- Upload image and auto-link to product
• unopim_upload_category_media -- Upload image and auto-link to category

Configuration

• unopim_get_channels -- List channels
• unopim_get_locales -- List locales
• unopim_get_currencies -- List currencies

Environment Variables

Required for stdio mode / Optional for HTTP mode (enables API key auth)

Variable	Description
UNOPIM_BASE_URL	UnoPim API URL (e.g., http://localhost:8000)
UNOPIM_CLIENT_ID	OAuth2 Client ID
UNOPIM_CLIENT_SECRET	OAuth2 Client Secret
UNOPIM_USERNAME	API username
UNOPIM_PASSWORD	API password

Optional

Variable	Default	Description
UNOPIM_DEFAULT_LOCALE	en_US	Default locale
UNOPIM_DEFAULT_CHANNEL	default	Default channel
UNOPIM_DEFAULT_CURRENCY	USD	Default currency
PORT	3000	HTTP server port
MCP_API_KEY	Value of UNOPIM_CLIENT_ID	API key for shared-credential auth
MCP_TOKEN_EXPIRY_SECONDS	86400 (24h)	OAuth token expiry
MCP_LOCK_BASE_URL	unset	Set to true to lock URL field in login form

Docker

The server is packaged as a Docker image (node:20-alpine). See the unopim-deploy repo for the Docker Compose setup.

docker compose build mcp
docker compose up -d

Development

npm install
npm run build        # Build TypeScript
npx tsc --noEmit     # Type check only

Project Structure

src/
  index.ts              # Stdio transport entry point
  index-http.ts         # HTTP transport with OAuth + per-session servers
  config.ts             # Environment configuration
  auth/
    oauth.ts            # UnoPim OAuth2 token management
    mcp-oauth.ts        # MCP OAuth server (PKCE, stores, token exchange)
    login-form.ts       # HTML login form with localStorage
    client-registry.ts  # Per-user UnoPimClient cache
  client/
    unopim-client.ts    # HTTP client with retry logic
  tools/
    registry.ts         # Shared tool registry
    register-all.ts     # Tool registration
    schema.ts           # Schema discovery
    attributes.ts       # Attribute CRUD
    families.ts         # Family management
    categories.ts       # Category management
    category-fields.ts  # Category field management
    groups.ts           # Attribute groups
    products.ts         # Product CRUD + media upload
    configuration.ts    # Channels, locales, currencies
    delete.ts           # Delete operations
  prompts/
    index.ts            # MCP prompt handlers
  types/
    errors.ts           # Error types
    oauth.ts            # OAuth + MCP auth types
    unopim.ts           # UnoPim API types

Tech Stack

• Node.js 20, TypeScript
• @modelcontextprotocol/sdk, zod
• No other runtime dependencies -- OAuth uses Node.js built-in crypto

License

ISC