UnoPim MCP Server

Version 3.0.0 -- A Model Context Protocol server that connects Claude Desktop (and other MCP clients) to a UnoPim PIM instance (UnoPim v3 / 3.0.x, self-hosted or Cloud Hosting). Provides 15 consolidated, action-based tools for managing attributes, families, categories, products, media, association types, variant structures, measurements, and settings.

3.0.0 — UnoPim v3

This release targets UnoPim 3.0.x and is a breaking change from 2.x. It will not work against a 2.x UnoPim instance, and a 2.x version of this server will not work against a v3 instance.

Requirements

• UnoPim 3.0.x (self-hosted or UnoPim Cloud Hosting)

• Node.js 20+

Breaking changes

• Tool set consolidated: 36 old per-verb tools → 15 action-based tools (one tool per resource, action parameter selects the operation). Full mapping:

• unopim_smart_create_product and unopim_get_family_schema are gone. Use unopim_products action=create (family validation happens against the real family) and unopim_families action=get respectively.

• Authentication changed: OAuth2 password grant now sends client credentials via an Authorization: Basic header instead of the JSON body. No config change needed — the server builds the header internally from UNOPIM_CLIENT_ID/UNOPIM_CLIENT_SECRET — but tokens and cached OAuth sessions issued against a 2.x instance are invalid after the instance is upgraded to v3. Re-authenticate (HTTP mode) or regenerate API credentials (stdio mode) after a UnoPim upgrade.

• Pagination defaults to 10 and clamps to 100 per request — tools now follow links.next internally where relevant; if you built anything against the raw API, don't assume limit above 100 is honored.

• Product associations moved to the top level of the product payload (a sibling of values, not nested inside it).

New capabilities

• unopim_measurements — measurement families, units (with conversion factors), and attribute↔unit bindings.

• unopim_association_types — custom product-relationship types (e.g. spare parts, accessories) with per-link fields.

• unopim_variant_structures — 1-/2-level variant axes per family with per-level attribute placement.

• unopim_settings — full CRUD (not just read) on channels, locales and currencies, enabling instance bootstrap from scratch.

• unopim_media — get/delete in addition to upload, plus a swatch target for attribute-option swatches. Product uploads are auto-linked server-side by UnoPim v3.

• Delta sync on unopim_products: updated_since filter shortcut plus pagination_type=search_after cursor pagination (simple products only).

• unopim_get_capabilities: deterministic, local self-description of every resource, filterable field, operator, pagination rule and rate limit — no trial-and-error required.

UnoPim Cloud Hosting ("SaaS")

UnoPim also ships as a managed offering — a dedicated, standard UnoPim instance per customer, same API, no code differences. Point UNOPIM_BASE_URL (or the HTTP-mode login form's base-URL field) at the tenant's assigned URL. Hourly API-call quotas apply per tier: Starter 5,000/hour, Pro 10,000/hour, Enterprise 25,000/hour (independent of the general 120 req/min rate limit).

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.

UnoPim v3 itself authenticates via OAuth2 password grant with client credentials sent as an Authorization: Basic header (handled internally — no config change needed).

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 (15)

Meta / Discovery (start here)

• unopim_get_schema -- Fetch the complete data model (fetches ALL pages)

• unopim_get_capabilities -- Deterministic self-description: resources, filters, operators, pagination, rate limits

• unopim_get_guide -- Step-by-step guides: product-import, configurable-products, troubleshooting

Data Model (action-based CRUD)

• unopim_attributes -- actions: list, get, create, update, delete, list_options, create_options, update_options, delete_option

• unopim_attribute_groups -- actions: list, get, create, update, delete

• unopim_families -- actions: list, get, create, update, delete, add_attributes

• unopim_variant_structures -- actions: list, get, create, update, delete (NEW in v3)

• unopim_categories -- actions: list, get, create, update, delete

• unopim_category_fields -- actions: list, get, create, update, delete, list_options, create_options, update_options, delete_option

Products

• unopim_products -- actions: list, get, create, update, patch, delete, upsert, bulk_create

• unopim_configurable_products -- actions: list, get, create, update, add_variant, delete (deleting a parent deletes ALL its variants)

• unopim_media -- actions: upload, get, delete × target: product, category, swatch (product uploads auto-link server-side)

v3 Features

• unopim_settings -- actions: list, get, create, update, delete × resource: channel, locale, currency

• unopim_measurements -- measurement families, units, attribute↔unit bindings (NEW in v3)

• unopim_association_types -- custom product-relationship types + per-link fields (NEW in v3)

Every tool's delete action is IRREVERSIBLE -- always confirm with the user first.

Environment Variables

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

Optional

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 (plain tsc)
npx tsc --noEmit     # Type check only
npm test             # Run the vitest suite -- run before considering any change done

Project Structure

src/
  index.ts              # Stdio transport entry point
  index-http.ts         # HTTP transport with OAuth + per-session servers
  config.ts             # Environment configuration
  version.ts            # Package version constant
  auth/
    oauth.ts            # UnoPim OAuth2 token management (v3: Basic-header client creds)
    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/
    endpoints.ts         # Typed endpoint catalog (paths/filters/pagination)
    unopim-client.ts      # HTTP client: envelope handling, ETag cache, retry/backoff, pagination
    resources.ts          # Generic ResourceClient (list/get/create/update/patch/delete + sub-resources)
  tools/
    registry.ts          # Shared tool registry
    register-all.ts      # Registers all 15 consolidated tools
    crud-factory.ts       # Factory for action-based CRUD tools
    product-helpers.ts     # Shared product payload/error/orphan helpers
    schema.ts             # unopim_get_schema
    capabilities.ts        # unopim_get_capabilities
    guides.ts              # unopim_get_guide
    attributes.ts          # unopim_attributes
    groups.ts              # unopim_attribute_groups
    families.ts            # unopim_families
    variant-structures.ts  # unopim_variant_structures
    categories.ts          # unopim_categories
    category-fields.ts     # unopim_category_fields
    products.ts            # unopim_products
    configurable-products.ts # unopim_configurable_products
    media.ts                # unopim_media
    settings.ts             # unopim_settings
    measurements.ts          # unopim_measurements
    association-types.ts     # unopim_association_types
  prompts/
    index.ts            # MCP prompt handlers
  types/
    errors.ts           # Error types (v3 error envelope)
    oauth.ts             # OAuth + MCP auth types
    unopim.ts            # UnoPim API types
skills/                  # Content served by unopim_get_guide

Tech Stack

• Node.js 20, TypeScript

• @modelcontextprotocol/sdk, zod

• vitest for tests

• No other runtime dependencies -- OAuth uses Node.js built-in crypto

License

ISC