MCP server

@minipim/mcp is a Model Context Protocol server that lets AI agents read and improve your catalog. It talks to the public minipim API with an API key, so an agent can only do what the API allows.

Setup

Create an API key under System → API keys, then add the server to your client.

Claude Code:

claude mcp add minipim --env MINIPIM_API_KEY=pim_… -- npx -y @minipim/mcp

Claude Desktop, Cursor or any stdio client:

{
  "mcpServers": {
    "minipim": {
      "command": "npx",
      "args": ["-y", "@minipim/mcp"],
      "env": { "MINIPIM_API_KEY": "pim_…" }
    }
  }
}

HTTP clients (n8n, Zapier, Make and similar): run MINIPIM_API_KEY=pim_… npx -y -p @minipim/mcp minipim-mcp-http, which serves /mcp on port 4200, and point the client at that URL.

Then ask the agent to run check_connection. It reports the API version, the organization the key resolves to and the product count. Confirm the organization is the one you meant.

Tools

Tool	Does
get_catalog_overview	Counts by status, families, channels with their required attributes, locales, top categories, brands, tags
get_family_schema	Every attribute a family accepts, with the expected value shape
search_products	Find products by text and filters (up to 100 per call)
get_product	One product with attributes, categories, media, variants, identifiers and relationships
find_incomplete_products	Products scored against their channels’ required attributes, worst first
get_product_completeness	Per-channel score and gaps for one product
set_product_attributes	Write: set or clear attributes on one product
bulk_update_products	Write: one change across up to 100 product ids. Dry run unless apply: true
set_variant_identifiers	Write: UPC, GTIN, MPN or SKU on a variant, with check-digit validation
check_connection	Which catalog the key points at, and whether it works

Prompts: audit-catalog (read only), enrich-catalog and prep-for-channel. Clients usually show them as slash commands.

Configuration

Variable	Default	Notes
MINIPIM_API_KEY	none	Required. Must start with pim_
MINIPIM_BASE_URL	https://api.minipim.com	Set this for a self-hosted instance
MINIPIM_READ_ONLY	false	1 or true removes the three write tools and the two writing prompts
PORT	4200	HTTP transport only

Rules and limits

• MINIPIM_READ_ONLY is a client-side switch: the server simply does not register write tools. In read-only mode only audit-catalog is offered.
• bulk_update_products has no filter parameter. Pass explicit ids, usually from search_products or find_incomplete_products. mode: "replace" on tags or categories discards what is there, and familyMode: "drop_unsupported" deletes values the new family does not declare.
• set_variant_identifiers adds by default. Replacing a variant’s whole identifier set needs mode: "replace" plus apply: true.
• Writing a localizable attribute requires a locale.
• Completeness is scored against each channel’s required attribute list, which can differ from the family’s required attributes. See Attribute families.
• Variant identifier gaps are closed with set_variant_identifiers, not product attributes. See SKUs and identifiers.
• The server has no tools for deleting products, wiping the catalog, managing members or keys, deleting organizations, or triggering connector syncs.
• The HTTP transport authenticates from its own environment, so one running server serves one key and one catalog. Do not expose it publicly.
• Agent writes go through the API like any other, so they appear in the audit log and fire webhooks.