Shopify Catalog MCP Bridge

A small, unofficial, MIT-licensed compatibility bridge between Shopify's global Catalog MCP endpoint and standard MCP clients, including Open WebUI. Not affiliated with or endorsed by Shopify.

Why a bridge?

Shopify's endpoint advertises search_catalog, lookup_catalog, and get_product. Every call requires a UCP agent profile, and observed catalog responses contain structuredContent without content. Some MCP SDKs reject that response.

This bridge:

• Uses the official MCP TypeScript SDK and stateless Streamable HTTP at /mcp.

• Injects your configured profile into arguments.meta.ucp-agent.profile.

• Removes that metadata field from the model-facing input schema.

• Preserves structured results and adds a JSON text content block for clients.

• Exposes only the three read-only catalog tools, never cart or checkout tools.

• Preserves upstream JSON-RPC errors, tool errors, and HTTP rate-limit metadata.

• Does not retry, cache catalog responses, download images, or forward incoming credentials, cookies, request headers, or user information to Shopify.

The upstream response issue is documented in the prepared Shopify report. This is a compatibility adapter, not an Open WebUI plugin or a replacement catalog implementation.

Related MCP server: UCP MCP Storefront

Quick start

Requires Node.js 24 or later:

npm ci
npm run build
export UCP_PROFILE_URL=https://shopify.dev/ucp/agent-profiles/2026-08-25/valid-with-capabilities.json
npm start

The server binds to 127.0.0.1:8080 by default. Use a separate terminal:

curl --fail http://127.0.0.1:8080/healthz

UCP_PROFILE_URL is required deliberately: profile ownership is part of the agent's identity. The URL above is Shopify's hosted example profile, useful for evaluation; it is not a profile you own. For production, publish your own UCP profile with the catalog search and lookup capabilities and appropriate Shopify extensions.

Docker

Published multi-architecture images support linux/amd64 and linux/arm64.

docker run --rm -p 127.0.0.1:8080:8080 \
  -e UCP_PROFILE_URL=https://shopify.dev/ucp/agent-profiles/2026-08-25/valid-with-capabilities.json \
  ghcr.io/gregcar/shopify-catalog-mcp-bridge:v0.1.0

Or build locally: docker build -t shopify-catalog-mcp-bridge .

Open WebUI

In Admin Settings > Integrations > External Tool Servers, add:

The URL must be reachable from the Open WebUI backend. For separate Docker containers, use a shared Docker network and the bridge's container/service name, not localhost. Add that name to ALLOWED_HOSTS.

Select Shopify Catalog from a chat's tools menu and use a model that supports tool calling. No profile instructions are needed in the prompt. For example:

Find wireless headphones shipping to Canada and compare three options.

Prices are in currency minor units; follow Shopify's tool descriptions when displaying them. Product discovery can return checkout links but does not place orders.

Configuration and boundaries

Deploy only on a trusted private network or behind authenticated TLS. BRIDGE_TOKEN is a shared service credential, not per-user authorization. The bridge does not implement OAuth or browser CORS access. Browser Origin requests are rejected. /healthz is unauthenticated and reports process health, not Shopify availability.

Kubernetes HTTP probes need an allowed Host header, such as localhost. Allow only intended MCP clients with network policy. The image runs as the unprivileged node user and supports a read-only root filesystem.

All catalog traffic goes to the fixed Shopify global endpoint; caller-controlled upstream destinations and arbitrary proxying are not supported. Shopify fetches the configured profile itself. Requests time out after 30 seconds, upstream responses are limited to 8 MiB, and HTTP request bodies use the SDK's bounded JSON parser. HTTP 429 becomes MCP error -32029 with data.status and data.retryAfter; callers should honor it rather than retrying immediately.

Search terms and tool arguments are sent to Shopify. No request bodies, credentials, or product results are intentionally logged or persisted. Client applications may independently retain chat/tool history. Follow Shopify's catalog usage guidelines: do not cache catalog results or download images to your servers; render images live in connection with their merchant listing.

Development and verification

npm ci
npm run typecheck
npm test
npm run test:live

Unit/integration tests use mocked Shopify responses and the official MCP client. The opt-in live smoke test sends one public product search to Shopify using the hosted example profile unless overridden. It does not place orders, cache results, or print product payloads.

GitHub Actions runs tests for pushes and pull requests. Version tags matching the package version publish GHCR images and smoke-test the resulting container. Production deployments should pin the published image digest.

Contributions with tests and focused scope are welcome. Please do not include private chat transcripts, API tokens, or customer data in issues.

License

MIT.