MCP server Rubik Variant Images & Swatch
The MCP server lets AI assistants like Claude work with your variant images. Once connected, you can simply ask your assistant to do things like "assign the right photos to each color of my new hoodies" or "hide sold-out swatches storewide", and it happens in your store, using the same reliable operations as the app itself.
MCP (Model Context Protocol) is an open standard supported by Claude and a growing number of AI tools. Rubik Variant Images & Swatch ships a built-in MCP server, so there is nothing to install: you create a connection token in the app and add it to your assistant.
What you can do with it
You talk to your assistant in plain language, and it carries out the work in your store using the same operations as the app. Here is the full range, grouped by task. Every quoted line below is something you can actually say.
Understand your store and setup
Ask about your plan and how many products you can still configure, whether the variant images, swatches and product-card swatches are switched on, and read every app setting.
How many products have variant images set up, and how many more can I configure on my plan?
Are swatches turned on for product cards?
Find products that need images
List the products that are not configured yet, with the same filters as the app's Products page: search, status, vendor, product type, tags, collection, option name, and "at least two images" so the assistant skips products that cannot be configured anyway.
Which active products with a Color option still have no variant images assigned?
Show me the unconfigured products tagged summer that have several photos.
Assign variant images
Open a product to see its options, option values, images (with file names and alt text) and variants, then assign images to each option value. The assistant can match images to values by their file names or alt text, or by looking at the pictures, and it can set each variant's featured image and reorder the product's media as part of the same step, exactly like the app's assign page. New configurations count against your plan's limit, and the assistant checks that first.
Open the Aurora hoodie and assign each photo to the color it shows.
Configure every product from the Nike vendor: the file names say which color each image belongs to.
Add the two new photos to the Blue value of the Aurora hoodie and keep the rest as it is.
Review and clean up
List your configured products, most recently configured first, check what a product has assigned, and remove a configuration you no longer want. Removal is always confirmed with you first, because it cannot be undone.
Which products did I configure this week?
Remove the variant image configuration from the discontinued Boot Mini.
Set a product's swatch colors and images
Give one product's option values their own swatch, the same as the app's Edit swatches page: a color, a two-tone pair of colors, or one of that product's own photos. The assistant reads what each value has now, then sets or clears the color and the image independently, so changing a color leaves a picked image alone. It can choose the colors by looking at the photos rather than trusting the file names. This touches only the product you name and uses none of your plan's product slots. The shop-wide library (Bulk set swatches) stays in the app.
Look at the Aurora hoodie's photos and give each color value a matching swatch color.
Use the close-up fabric photo as the Blue swatch on this product, and clear its color.
Make Sand a two-tone swatch: beige with a cream second color.
What swatches does the Boot Mini have set right now?
Restyle the swatches with CSS
The assistant can restyle the swatches on product pages by writing the same Custom CSS the style editor's Custom CSS box holds, guided by the complete variable reference (135 variables with defaults). Overrides win over the editor's output and are removed by clearing the field, so the editor stays in charge. Product cards and the editor's structured controls remain in the app.
Make the swatches round with a blue selected border.
Remove the hover zoom and shadow.
Ask how the app works
The assistant can read this documentation site itself, so it can answer questions about setup, the theme app embed, plans and limits, swatch styling, custom CSS, supported themes and page builders, or the swatch click event, and point you to the right page in the app for anything it cannot do for you.
I installed the app but nothing shows on my product page. What should I check?
Can I make the swatches round and bigger?
Configure app-wide settings
Change the settings from the app's Settings and Swatch pages: the variant images master switch, image assignment rules, hiding unassigned images, which option names render as swatches, hiding deleted or sold-out variants, native Shopify swatches, dropdowns, tooltips, layout, and the product-card swatch behaviour. Updates are partial, so the assistant changes only what you ask and leaves everything else untouched.
Hide sold-out image swatches across my whole store.
Turn on product-card swatches and show only the first option on cards.
Everything it can do, at a glance
These are the exact capabilities your assistant sees when it connects. Read capabilities only look; write capabilities change your store and appear on the storefront immediately.
| Capability | What it does | Access |
|---|---|---|
| Shop info get_shop_info | Your plan and how many products you can still configure, what every plan costs and allows, whether variant images, swatches, card swatches and the theme app embed are on, anything currently switching the app off on your storefront, and your admin language. | Read |
| List products list_products | Your products with the Products page filters: not configured / configured / all, search, status, vendor, type, tags, excluded tags, collection, option name, at least or fewer than two images, and sorting. Only products that have variants are listed, since a product without them cannot have variant images, and archived products stay out unless you ask for them. | Read |
| Configured products list_configured_products | The products with a variant image configuration, from the app's own records so the list is exact: which option the images were assigned to and when, most recently configured first, with a title filter. | Read |
| Product details get_product | One product in full: options and values, images with file names and alt text, variants, and the current image assignment, fetched live from Shopify. | Read |
| Assign images configure_product | Assign images to a product's option values, optionally setting variant featured images and the media order. Replaces or merges with the current assignment. | Write |
| Remove configuration remove_product_configuration | Remove a product's variant image configuration and free its plan slot. Always confirmed with you first. | Write |
| Swatch style get_swatch_style | Reads your custom swatch CSS and, for context, the stylesheets the style editor generated. | Read |
| Update swatch style update_swatch_style | Replaces your custom swatch CSS (the style editor's Custom CSS field) to restyle product-page swatches; an empty value restores the editor's styling. | Write |
| Product swatches get_product_swatches | Reads a product's own swatches, live from Shopify: the color, second color and image on each option value, and whether swatches are switched on for your store. | Read |
| Set product swatches set_product_swatches | Sets a product's own swatches (the Edit swatches page): per option value, a color, a two-tone color pair, or one of that product's photos, and clears any of them. Only the slots you name change. | Write |
| Documentation get_docs | Reads this documentation site (index or a full page) to answer questions about the app. Never touches your store. | Read |
| App settings get_settings | Every shop-wide setting from the Settings, Swatch and Swatch style pages with its current value, plus warnings about combinations that would render nothing. | Read |
| Update settings update_settings | Change any of those settings. Partial: only the settings you name change. Switching variant images or swatches back on is refused while your store is over its plan limit, and showing swatches on unconfigured products needs a paid plan. | Write |
Example conversations
Configure a product
You: "Set up variant images for the Aurora hoodie."
Claude opens the product, sees the Color option with Red, Blue and Black, matches the six photos to the colors by their file names, assigns two to each, and tells you it is live. The product page now shows only the photos of the selected color.
Work through a whole vendor
You: "Configure every unconfigured product from Acme that has at least two photos."
Claude checks how many slots your plan has left, lists the matching products, and configures them one by one, reporting the products whose photos it could not match so you can finish those in the app.
Tune settings across the store
You: "Hide sold-out swatches and show my Size option as a dropdown instead of buttons."
Claude flips those settings and leaves the rest of your configuration untouched, then confirms what changed.
Read-only or full access
You choose the access level for each connection, and you can keep up to five active connections at once with different levels. Revoke one you no longer use to make room for a new one.
- Read-only can view everything: your setup, settings, products and image assignments. It can never change anything. Ideal for reporting, audits, or just letting an assistant explore safely.
- Full access can do everything read-only can, plus assign and remove variant images and change settings. Every change goes live on your storefront immediately, exactly as if you had made it in the app.
Create a connection
1Open the MCP server page
In the app, open MCP server from the navigation menu, then select Create connection.
2Name it and choose the access level
Give the connection a name you will recognize later (for example "Claude on my laptop"). Then pick the access level:
- Read-only: the assistant can look at your products, image assignments and settings, but can never change anything. A safe way to start.
- Full access: the assistant can also assign and remove variant images and change app settings.
3Copy your token
The token is shown only once, right after you create the connection. Copy it and store it somewhere safe. If you lose it, revoke the connection and create a new one.
Connect your assistant
Claude Code (terminal)
Paste the ready-made command from the app, or build it yourself:
Claude Desktop
Claude Desktop connects to HTTP MCP servers through a small local proxy. Add this to your claude_desktop_config.json (Settings → Developer → Edit config), then restart Claude Desktop:
The token is passed via the env value (note: no space around the colon in the --header argument). This form avoids a known Claude Desktop on Windows bug where spaces inside arguments get mangled.
claude.ai custom connectors
claude.ai custom connectors currently authenticate with OAuth only, so they cannot use these bearer tokens yet. OAuth support for one-click setup is planned. For now, use Claude Code or any MCP client that accepts a custom header (below).
Other MCP clients
Any client that supports MCP over Streamable HTTP with a custom Authorization header works. Use the server URL https://rubikvariant.com/mcp and send Authorization: Bearer YOUR_TOKEN with each request.
Tip: once connected, start by asking your assistant something like "What can you do with my variant images?" or "How many products are configured?" to confirm everything works.
Good to know
- One store per connection. A token only ever works with the store it was created in.
- Changes are immediate. A full-access change appears on your live storefront right away, the same as making it in the app.
- Current data. Product details are read live from Shopify, so options, images and variants are exactly what your store holds at that moment. Product lists come from Shopify's search index, which can lag a few minutes behind a product you just changed; the assistant is told how many rows that hid and keeps paging.
- Plan limits apply. New configurations use your plan's product slots exactly like the app; when the limit is reached the assistant tells you and points you to the upgrade.
- One change at a time. Assigning images, removing a configuration and setting a product's swatches run one per store at a time, so a long bulk run stays steady and two assistants can never collide on the same product. A change that arrives while another is still running is turned away with a "try again", and the assistant retries it once the first finishes.
- Removal is always confirmed. The assistant will not remove a product's configuration without your explicit go-ahead.
- Per-store limits. Connections are rate limited per store so an assistant can never overload your setup. Reading a handful of products or changing settings stays well inside them. A long bulk run will reach them: the assistant is told how many seconds to wait, and a good one waits and carries on, so a large catalog is configured steadily over a longer session rather than all at once.
- Focused scope. The assistant works within Variant Images: your image assignments, swatch settings, and this app's settings. It does not reach into the rest of your Shopify admin.
- Works alongside the app. Anything an assistant changes shows up in the app's screens too, and vice versa. You can keep editing in the app whenever you prefer.
Security
- Per-store tokens. A token only ever gives access to the store it was created in.
- Shown once, stored hashed. The token itself is stored only as a cryptographic hash; nobody, including us, can read it back. We keep the first few characters so you can tell your connections apart in the list, which is not enough to use.
- Read-only by default. Full access is an explicit choice when you create a connection.
- Revoke anytime. Revoking a connection takes effect immediately; assistants using that token stop working on the spot.
- Removal takes a deliberate step. Removing a product's configuration is marked destructive and only runs when the assistant explicitly confirms it, which is what makes your assistant ask you first and what makes most MCP clients show you an approval prompt.
- Rate limits. Connections are rate limited per store, so a misbehaving assistant cannot overload your setup.
- Uninstall safety. If you uninstall the app, every connection stops working automatically.
Troubleshooting
- Authentication errors: the token was mistyped, was revoked, or belongs to an install that has since been removed. Uninstalling the app revokes every connection, and reinstalling does not bring them back, so create a fresh connection and update your assistant with the new token. Tokens you create in the app do not expire on their own. After several failed attempts in a row you will see "Too many failed authentication attempts" instead; wait a minute before trying the corrected token.
- "Rate limit exceeded" messages: the assistant is calling faster than the per-store limits allow. It should wait the indicated number of seconds and retry; no action needed from you.
- "Another write is already running": two assistants (or two parallel requests) tried to change products at the same time. The second one should simply retry after the first finishes.
- "Plan limit reached" when configuring: your plan's product limit is used up. The message includes a link to upgrade.
- Shopify API errors right after a long break: open the app once in your Shopify admin, then try again.
- "Something went wrong on our side" with a reference id: something failed unexpectedly. Send us the reference id and we can look up exactly what happened on that call.
Not supported yet
- claude.ai custom connectors. They require OAuth, which these bearer tokens do not use yet. One-click OAuth setup is planned. For now, connect with Claude Code, Claude Desktop, or any client that accepts a custom header.
- Some app features aren't exposed to assistants yet: the swatch style editor's structured controls and product-card styling (assistants restyle product pages via custom CSS instead), the shop-wide swatch library (Bulk set swatches), the AI bulk assign jobs, turning the theme app embed on, and changing your plan. An assistant can tell you that the embed is off or that your plan is full, but the switch and the upgrade are yours to make in the Shopify admin. Ask an assistant for those and it will point you to the right page in the app instead of attempting them. If you would use any of them through an assistant, tell us and we will prioritize them.
Questions or ideas for new assistant capabilities? Contact support, we would love to hear how you use it.