Optimize images and alt text with Paperclip
Fixing image SEO from Paperclip means tasking an agent to find the heaviest or unlabelled images in StoreSEO, report the plan and its quota cost on the ticket, and compress or label them only once you start the run that does the writing.
Last updated: October 2026
Set up Paperclip for StoreSEO
Skip this if Paperclip is already connected. The full guide, with the alternatives, is on the Paperclip page.
- 1
Add StoreSEO to the agent Paperclip runs
Run this on the machine that hosts the agent, as the same OS user the Paperclip heartbeat runs as, from the agent's working directory. It is the claude_local adapter path, and user scope makes StoreSEO available to every Claude Code agent that user runs.
terminalclaude mcp add --transport http --scope user storeseo https://mcp.storeseo.com/mcp
- 2
Sign in once, then let Paperclip run headless
Start claude interactively as that same user, run /mcp, choose storeseo and finish the browser sign-in: pick your Shopify store and approve. Claude Code keeps the credentials, so later Paperclip runs need no browser. Check with claude mcp get storeseo.
new message to Paperclip/mcp
Step-by-step guide in the docs: How to connect StoreSEO MCP to Paperclip
How does this work in Paperclip?
Image work has a natural two-task shape in Paperclip. The first task is a survey: you ask the agent to find product images with no alt text and the heaviest unoptimized files, and it calls storeseo_list_images, optionally scoped to one product by title. Because a title search can also match file names from other resources, a careful agent checks that each row belongs to the product you named before it reports. The result is a list on the ticket with file sizes, missing alt text and a count, and every call so far is a read.
The second task does the writing, and it is where cost matters. storeseo_optimize_image works on one image per call and can run compression, file naming and alt text together. Compression uses the Image Optimizer add-on's monthly quota, while alt text and file names spend AI Content Optimizer credit, and a renamed file changes the image's storefront URL. So the ticket should state the number of images and which of the three axes to run, and the agent should say in a comment what that will spend before it starts. A long batch is a poor fit for an agent with a tight Paperclip budget, since each image is its own call.
If a result is wrong, a follow-up task can call storeseo_restore_image for that one image, per axis. Keep the survey on a schedule if you like, and keep the optimizing in a run you supervise.
-
You: Ticket: list images on Canvas Tote with no alt text, and say what fixing them would cost.
- storeseo_list_images read-only
-
Paperclip: Canvas Tote has four images and three have no alt text. Writing alt text spends AI credit per image, and a new file name would change the image URL. Write alt text for the three and leave the file names alone?
-
You: Yes, alt text only.
- storeseo_optimize_image needs approval
- storeseo_list_images read-only
-
Paperclip: Alt text applied on the first image. I re-listed to confirm before moving to the next two, and I am reporting each result on the ticket.
What to ask Paperclip
Tap a prompt to copy it, then paste it into Paperclip.
What StoreSEO does: image seo and alt text
StoreSEO tracks three things per image: file-size compression, alt text and file name. The agent finds the heaviest or unlabelled images, optimizes them one call per image, and can restore any of the three if you do not like the result.
Requires: Compression needs the Image Optimizer add-on and counts against its monthly quota; alt text and file names spend AI Content Optimizer credit.
- 1
Find the images
The agent lists product, collection or article images, heaviest unoptimized first by default. It can filter to images with no alt text, or scope the list to one product by title.
- 2
Check what it found
A title search can also match image file names from other resources, so the agent checks each row belongs to the product you meant.
- 3
Agree the scope and cost
Compression uses image quota and alt text and file names use AI credit, so the agent confirms before working through many images.
- 4
Optimize one image per call
Each call takes the axes you want: compression, alt text, file name or all three. The axes always run compression, then file name, then alt text, and the response reports each one separately.
- 5
Report or restore
The agent reports what applied, what was already done and what was refused. If a result is wrong, the restore tool brings back the original file, alt text or name.
Image SEO and alt text reference
| Axes per image | Compression, alt text, file name |
|---|---|
| Image sources | Products, collections and articles (pages have no images) |
| Batching | One image per call; never two calls on the same image at once |
| Compression | Image Optimizer add-on and its monthly quota; an already compressed image is reported as already applied |
| Alt text and file name | AI Content Optimizer credit; both together are billed as one generation |
| File name change | Renames the file on Shopify and changes the image's storefront URL |
| Collection and article renames | Re-upload the image, so the call can take a couple of minutes |
| Restore | Reverts compression, alt text or file name per axis |
| Score impact | Alt text and file names count on products, collections and articles; compression counts on products |
Rules Paperclip follows
- The agent confirms the number of images and the kind of spend before a bulk run.
- One image per call, all wanted axes together; never parallel calls on the same image.
- A renamed image has a new URL, so the agent tells you, because anything that hard-coded the old URL keeps serving the old file.
- If a response is lost, the agent re-lists the image instead of retrying, because a retry regenerates and spends again.
- A refused axis, for example compression without the add-on, is reported as such while the other axes still apply.
In Paperclip
Do not let a headless run retry an image call on its own. If a response is lost, the right move is to re-list the image, because a retry regenerates alt text and spends credit again. Paperclip heartbeats can wake an agent mid-batch, so write the ticket to say one image per call and re-list before any retry. With the Claude Code adapter's default of skipping permission prompts, nothing else will stop a long optimizing loop, so set the batch size in the task text.
What runs without asking. Reads such as SEO scores, store listings, settings and Google reports run straight away. Generating a preview spends AI credit but writes nothing, and StoreSEO tells the agent to say what a generation will cost before it runs one. Applying content, optimizing images, changing settings, publishing llms.txt or agents.md, writing a product description and deleting anything wait for your yes in the conversation. That yes is an instruction the agent follows, not a lock on the server, so your client's own tool-approval setting is the hard stop.
Questions
Can a Paperclip routine compress my product images every week?
It is better not to. Compression counts against the Image Optimizer add-on's monthly quota and alt text spends AI credit, and a routine has nobody to approve the spend. Schedule the survey that lists images, and run the optimizing in a task you start.
What does the agent do if image compression is refused?
StoreSEO reports the refused axis, for example compression without the add-on, and still applies the others you asked for. The agent should post that split on the ticket so you see what applied and what did not.
Can the agent compress images without the Image Optimizer add-on?
No. Compression needs the Image Optimizer add-on and counts against its monthly quota. Alt text and file names work without it and spend AI Content Optimizer credit instead.
Can I undo an image optimization?
Yes. The restore tool reverts compression, alt text or file name for one image, per axis. Restoring compression brings back the original file.
Why did my image URL change?
Giving an image a new file name renames the file on Shopify and re-points its storefront URL. Pages that use the image through Shopify keep working, but anything that hard-coded the old URL keeps the old file.
Can I write my own file name or alt text through the agent?
No. StoreSEO writes the alt text and file name from the resource's own context. You can steer the language, and you can always edit alt text yourself in Shopify admin.
Keep going
Image SEO and alt text with other agents
More Paperclip guides