Image SEO and alt text Optimize images and alt text with Claude Code
Fixing image SEO with Claude Code means asking Anthropic's terminal agent to list your heaviest and unlabelled Shopify images through StoreSEO, then compress them and write alt text and file names one image per call, while it checks your theme code for the URLs a rename changes.
Last updated: October 2026
Set up Claude Code for StoreSEO
Skip this if Claude Code is already connected. The full guide, with the alternatives, is on the Claude Code page.
- 1
Add StoreSEO to Claude Code
Run this in any terminal. The user scope makes StoreSEO available in every project on your machine.
Terminalclaude mcp add --transport http --scope user storeseo https://mcp.storeseo.com/mcp
- 2
Sign in to your store
Start Claude Code, run /mcp, choose storeseo and follow the browser window: pick your Shopify store and approve access.
Prompt/mcp
How does this work in Claude Code?
You run Claude Code in the theme repository and type a request such as list my twenty heaviest product images and flag any with no alt text. It calls storeseo_start, then storeseo_list_images, and the calls scroll past in the terminal as reads. Each row carries the status of compression, alt text and file name, so Claude Code can sort the worklist by size or by missing alt text and write it to a file in the folder if you want to work through it over a few sessions.
The terminal changes what happens around the fix. Before it optimizes anything, Claude Code can search the repository for the file names it is about to change, because a new file name gives the image a new storefront URL and any Liquid section or JSON template that hard-coded the old URL keeps serving the old file. You see that grep result in the same session, decide which images are safe to rename, and only then approve storeseo_optimize_image. Each call handles one image and returns a per-axis report, which Claude Code can append to a changelog file so you have a record of what was compressed, renamed or refused.
If a result is wrong, you ask for a restore and Claude Code calls storeseo_restore_image for the axes you name. Because the session stays open, you can alternate between listing a batch, optimizing it, and re-listing to confirm the status columns changed, which is also how you recover when a response is lost: Claude Code re-lists the image instead of retrying, since a retry would regenerate and spend again.
-
You: List my heaviest images and check if the theme hard-codes any of their file names.
- storeseo_start read-only
- storeseo_list_images read-only
-
Claude Code: The heaviest ten are 2 to 6 MB. I searched the theme: hero-tote.jpg is referenced in sections/hero.liquid, so I would leave that file name alone and only compress it. Shall I compress all ten and add alt text to the nine that lack it?
-
You: Yes, but skip the rename on the hero.
- storeseo_optimize_image needs approval
-
Claude Code: First image: compression and alt text applied, file name untouched. Nine to go, one call each.
What to ask Claude Code
List my twenty heaviest unoptimized product images with StoreSEO, write them to image-worklist.md, and change nothing yet.
Before renaming any image files, grep this theme for the current file names and tell me which ones are hard-coded.
Compress and add alt text to the images on my Canvas Tote product, one call per image, and show me each report.
- Find my ten heaviest unoptimized product images and compress them. Tell me the quota it will use first.
- Which product images have no alt text at all? Write alt text for the ones on my best seller.
- Optimize every image on the product Canvas Tote: compression, alt text and file name.
- Restore the original alt text on the last image you changed.
- Give my collection images descriptive file names, and warn me which URLs will change.
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 Claude Code 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 Claude Code
Claude Code warns when one tool result passes 10,000 tokens, and a listing of images with all three status blocks can reach that on a large catalog. Ask for pages of twenty or filter to one product or to images with no alt text rather than the whole library. If you added an allow rule for the StoreSEO tools to stop prompts, it also covers storeseo_optimize_image and storeseo_restore_image, so a loose rule removes the pause on every image; scope it to the read tools if you only meant to speed up listing.
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 Claude Code tell me which theme files use an image before I rename it?
Yes, because it works in the folder you started it in. Ask it to search the theme for the current file name before you approve a rename, since a new file name changes the image's storefront URL and anything that hard-coded the old one keeps the old file.
Can Claude Code run image optimization on many images in one command?
Not in a single StoreSEO call. The tool takes one image per call, so Claude Code works through a batch as a series of calls and reports each result, and you should keep the batch to a size you are happy to review.
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 Claude Code guides