Tag Reference Images with Claude Code or Codex over MCP

Claude Code and Codex can tag your reference library through refern's built-in MCP server. Ask in plain language: find the untagged images, show a dry run, then apply. refern 1.10 runs every request through the same rules as its own tag picker, and it lists every change in Settings > Local API, where you can undo tag edits.

This guide assumes your app is already connected. If it is not, follow how to connect Claude Code or Codex to your reference library first.

Choose the right token

Tagging needs a Write token. Write lets the app search, edit item tags and details, create tags and creators, credit creators, run the Auto Tagger and review its suggestions, and undo its changes.

Building or editing tag hierarchies needs Organize. Organize also allows renames, moves, and Trash, so create that token for a specific task and revoke it after. No access level can delete files from disk. For moves, renames, and folders, see how to organize reference files with Claude Code or Codex.

Create a separate token for each app. The change list then shows which app made each change.

Step 1: Agree on the vocabulary

Before the app tags anything, have it read your existing tags. Tagging works best with a small, consistent vocabulary, and the app should reuse your words instead of inventing near duplicates.

"List my refern tags that contain 'light', and show me any aliases."

Tag names you give the app can be exact names or aliases. If "contre-jour" is an alias of your tag "backlight", asking for "contre-jour" applies "backlight". It does not create a second tag.

If you have no vocabulary yet, read the tag vocabulary guide for reference libraries before you hand the work to an assistant.

Step 2: Find untagged items

refern's search has an untagged mode. It finds items with no tags, and it can stay inside one folder or include its subfolders.

"Find the untagged images in my Inbox folder and its subfolders."

One search returns at most 200 items, and refern says when more matched. That limit is rarely a problem here: after you tag a batch, those items are no longer untagged, so the next search returns the next batch. Work one folder at a time for the clearest results.

Search also takes text, ratings, favorites, color labels, and dates added, so you can narrow the set:

"Find untagged images rated 4 or higher that were added this month."

For color, similarity, and meaning searches, see how to find reference images with Claude Code or Codex.

The app can look at an item's thumbnail before it suggests tags. Check its reasoning on a few items before you trust it with a large batch.

Step 3: Apply tags in bulk, with a dry run first

One edit changes up to 500 items and adds or removes up to 200 tags. Always ask for a dry run first. A dry run shows the changes item by item without saving them. It also lists any tags that do not exist yet.

"Add the tags hands and gesture to these 40 images. Do a dry run first and show me what would change."

Read the result. Then tell the app to apply it. In the same edit, the app can also remove a tag, clear all tags from the items, or set a rating, a favorite flag, a color label, notes, or a source.

Adding a tag keeps the item's other tags. If you only want to add one term, say "add". Do not ask the app to replace or clear tags unless you mean it.

Step 4: Create missing tags on purpose

By default, a tag name that does not exist makes the whole edit fail, and refern names the unknown tags. This protects you from typos such as "sunsett".

If a new tag is correct, say so:

"Create the tag foreshortening if it does not exist, then add it to these images."

The app can create the tag on its own, or create it during the edit when you allow new tags. A # and control characters are removed from new names, as in the app, and a name that already exists returns the existing tag.

How refern's tag rules apply

The app does not get a shortcut around your settings. A tag edit through the MCP server runs through the same engine as a tag edit in refern:

• Parent tags. A tag with its own parent rule follows that rule. Every other tag follows the workspace switch Apply parent tags automatically, in the Tag Manager's list of hierarchies. It is off by default, so asking for "hands" adds only "hands". Turn it on in the app if you also want "anatomy" added. The app cannot change this switch.
• Tag links. When a tag is in a linked set, applying it also applies the other tags in that set.
• Aliases. An alias resolves to its tag, as described in Step 1.
• NSFW rules. If a tag marks items NSFW, items that get the tag become NSFW. If your token hides NSFW items, those items then disappear from what the app can see.

The dry run shows what these rules would add, so you see the parent and linked tags before anything is saved.

Step 5: Build or extend a hierarchy

With a Write token, the app can create a new tag directly under an existing parent in a hierarchy:

"Create the tag fingers under hands in my Anatomy hierarchy."

Larger changes to structure need Organize. With it, the app can create hierarchies, categories, linked sets, and color styles (the API calls categories "tag groups" and linked sets "tag links"). It can also set a tag's own parent rule and its colors.

"Make a hierarchy called Lighting with rim light, side light, and backlight under a top-level tag light. Show me the plan before you save it."

Plan these changes carefully. Setting a structure's members replaces its whole member list, and that change cannot be undone from Settings. Creating and deleting tags and structures cannot be undone either. Ask the app to read the current structure first and to show you the full list it will save.

Step 6: Run the Auto Tagger and review its suggestions

The Auto Tagger is refern's optional on-device tagging model. It writes suggestions, not tags. With a Write token, the app can run it on the items you choose:

"Run the Auto Tagger on the untagged images in Inbox and tell me when it finishes."

A run takes up to 500 items and uses your saved Auto Tagger settings. Only one run happens at a time. It tags images and videos and skips other items. The model must be installed in refern first.

When the run finishes, the suggestions appear on each item. You decide what happens to them:

• Keep. Saves the suggestions you choose and marks the item as reviewed.
• Reject. Removes one wrong suggestion.
• Clear. Removes all suggestions from the item.

Keeping a suggestion does not add a real tag. To turn suggestions into tags, ask for a normal tag edit, with a dry run:

"For these images, add the suggestions cloud and sunset as real tags, but only where both were suggested. Dry run first."

If you prefer to review on screen, use the Review workspace in refern instead.

Step 7: Credit creators in order

Creators work like tags, and an item can have several in a set order. The app can create a creator and then set an item's credit:

"Credit this image to Ana Ruiz first and Leo Park second. Create them if they don't exist."

A name that is already a creator's name or alias returns that creator, so you do not get duplicates. Setting the credit replaces the item's creator list with the order you give.

Check the result and undo

Every change appears in Settings > Local API > Recent API changes, with what changed, how many items, which token made it, and when. Select Undo on a line to reverse it. Items that changed again since are skipped. You can also ask the app: "Undo your last tag change."

You can undo:

• Tag and detail edits on items, including bulk edits
• Creator credits on items
• Tag edits such as a rename, and creator edits
• Tag structure renames and recolors

These are listed but cannot be undone:

• Creating or deleting tags, structures, and creators
• Changes to a structure's members
• Auto Tagger runs and reviews
• Custom tag colors

refern keeps undo data for the newest 100 changes. A single change larger than 4 MB is saved without undo. If a bulk edit created new tags, Undo removes them from the items, but the tags stay in your list.

For tagging habits that work in the app as well as through an assistant, read how to tag reference images.

Limits to know

• Local only. The server listens only on your computer. Assistants that run only in a web browser cannot reach it.
• refern must be running with the workspace open. The app sees only that workspace.
• Your assistant may send data to its provider. refern does not upload your library, but an assistant whose model runs in the cloud sends what it reads, including thumbnails, to that provider.
• No file deletion. No access level can delete files from disk.
• License. The free trial lasts 30 days. After that, requests are refused until a license is active. A license is $35 once, for one user on up to three devices, on Windows, macOS, and Linux.
• Not a plugin system. The MCP server gives apps access to what refern already does.