Eagle MCP Plugin vs refern MCP Server: Which Should You Use?

Both Eagle and refern are tagged image libraries, and both now let an assistant app such as Claude Code work on the library through MCP (Model Context Protocol, a standard way for assistant apps to call tools in other apps). Choose Eagle's MCP / Skill plugin if you already use Eagle, want its quick Skill mode, and value its broader previews and plugin ecosystem. Choose refern's built-in Local API and MCP server if you want access with no plugin install, tokens with set access levels, no file deletion from disk, a change list with undo, Linux support, or a library that indexes your existing folders in place.

This page is written by refern. Eagle facts come from Eagle's MCP / Skill plugin post (checked October 11, 2026) and refern's June 2026 Eagle research. Where Eagle's sources do not describe something, this page says "not documented" instead of guessing. refern facts come from the refern 1.10 Local API reference and the guide the app serves to agents.

Quick verdict

Choose the Eagle MCP / Skill plugin if you live in Eagle

Eagle's plugin gives an assistant app plain-language control of an Eagle library. Eagle's post documents tag cleanup, folder restructuring, batch renaming with descriptive file names, tag translation, and image harvesting from websites you name. It offers two modes: Skill, which Eagle calls ready out of the box and recommends for most users, and MCP, which connects other agents and needs client configuration.

Eagle also keeps its other strengths: broader file previews, font management, and a Plugin Center with many community plugins. If your library is already in Eagle, adding one plugin is a smaller change than moving to another app.

Choose refern if you want built-in access with clear limits

refern's Local API and MCP server ship inside refern 1.10. You turn them on in Settings > Local API and create a token with a Read, Write, or Organize access level. No level can delete files from disk. Every change appears in Settings, and supported changes can be undone there. The server listens only on your computer, and refern runs on Windows, macOS, and Linux.

Try refern for 30 days if those limits match how you want an assistant app to work on your references.

Eagle MCP plugin vs refern MCP server at a glance

What can an assistant app do in each library?

Both connections cover the organizing work that is slow by hand. The difference is in how each one documents it. Eagle's post describes tasks. refern's reference describes the operations an assistant app can call, so the table below maps each Eagle task to the refern operations that do the same work.

Eagle's post also lists auto-categorization and batch updates. refern's reference has no single "auto-categorize" operation; an assistant app combines search, tagging, and moves to sort items, and it can run refern's Auto Tagger and read its suggestions.

Decision: Both can do the common cleanup jobs. Eagle documents ready-made task flows. refern documents each operation and its limits, which helps when you want to know exactly what an assistant app is allowed to change.

How do permissions, deletion, and undo compare?

This is where the two differ most, because Eagle's post does not document these areas.

refern has three access levels, and each one builds on the one before it:

• Read: browse, search, similar images, color search, thumbnails, and original files.
• Write: everything Read allows, plus item metadata and tags, creating tags and creators, groups and links, folder appearance, Auto Tagger runs and review, creating folders, imports, and undo.
• Organize: everything Write allows, plus rename, move, copy, linked copies, Trash and restore, folder and root hiding, editing and deleting tags and creators, tag structures, and smart folders.

According to the guide the app serves, a Read token sees 20 MCP tools and an Organize token sees 57. No level can delete files from disk, empty the Trash, or delete items permanently. Items moved to the Trash keep their files on disk. A token can also hide items marked NSFW, so they never appear in its results.

refern applies the same rules as the app: tag links, parent tags, NSFW rules, group rules, and tag and creator aliases. Every change is listed in Settings > Local API > Recent API changes. Changes to item metadata and tags, appearance, an item's creators, tag edits, creator edits, and Trash can be undone. Some changes are listed but cannot be undone: renames, moves, copies, imports, folder creation, groups and links, and tag deletions. Back up your library before you let an assistant app rename or move files. The reference library backup guide shows how.

Eagle's post describes a review step for several tasks: you see a cleanup plan, a folder plan, or a translation list and confirm it. The post does not document access levels, which actions the plugin can take, whether it can delete files, or how to undo a change.

Decision: If you want written limits before you hand an assistant app your library, refern documents them. If the review step in Eagle's task flows is enough for you, Eagle's plugin is a reasonable choice.

How do you set up each one?

Setting up refern

1. Open refern and go to Settings > Local API.
2. Turn on access for apps on this computer.
3. Create a token, give it a name and an access level, and copy it. refern shows it only once.
4. Add refern to your assistant app with the values that Settings shows.

For Claude Code, the reference gives this command:

claude mcp add --transport http refern http://127.0.0.1:7733/mcp --header "Authorization: Bearer rfn_..."

Settings also offers a ready-to-paste message for an agent that can run commands, and a Claude Desktop bundle. refern must be running with a workspace open; it can stay in the tray. A step-by-step guide for Claude Code and Codex is in how to connect Claude Code or Codex to your reference library.

Setting up Eagle

Eagle's post gives three steps: download the latest Eagle, open the Plugin Center and install the plugin found by searching "MCP", then choose Skill or MCP mode and follow Eagle's setup guide. Eagle recommends Skill mode for most users and says you do not need both. It notes that setup may take a little effort.

Decision: Eagle's Skill mode is designed for the fastest start. refern needs a token step, but every assistant app gets only the access you give it.

Does the assistant work locally or in the cloud?

refern's server listens only on 127.0.0.1, ports 7733 to 7743. Requests from web pages are refused, and cloud-hosted assistants cannot reach it. The assistant app must run on the same computer. A local API does not decide what your assistant app does with what it reads; that depends on the assistant app you choose.

Eagle's post does not document where the plugin's requests run. It names ChatGPT among its example clients but does not explain how each client reaches the library.

What about price and platforms?

refern's Local API and MCP server are part of the $35 one-time license for one user on up to three devices, with a 30-day free trial. Requests are refused when the trial has expired and no license is active. refern runs on Windows, macOS, and Linux.

Eagle costs $34.95 one-time for two devices, with a 30-day trial. The price of the MCP / Skill plugin is not documented in the sources used here. Eagle runs on Windows and macOS and has no Linux client.

How do the libraries store files?

The assistant app works on whatever the library holds, so storage matters too. Eagle's standard import copies files into the Eagle library. A normal refern workspace indexes your existing folders in place; explicit imports and copy actions can still create files. When an assistant app renames or moves an item in refern, the file on disk changes. Does Eagle copy your files? explains the difference in detail.

If you want to try refern's server with an existing Eagle library, the Eagle import guide shows what transfers.

Honest limitations of each

Eagle MCP / Skill plugin

• Its price, access levels, deletion limits, undo, and local or cloud behavior are not documented in its plugin post.
• It requires Eagle, which has no Linux client.
• Eagle's standard import copies files into its library.

refern Local API and MCP server

• It is off until you turn it on and create a token, and refern must be running with a workspace open.
• Only assistant apps on the same computer can connect. Cloud-hosted assistants cannot reach it.
• No access level can delete files from disk, so permanent cleanup stays a manual step in the app.
• Renames, moves, imports, and tag deletions are listed but cannot be undone.
• The reference has no tag merge operation.
• It is not a plugin system, and refern has none. refern also previews fewer formats than Eagle.
• It stops working when the trial has expired and no license is active.

Final decision

Choose the Eagle MCP / Skill plugin if your library is in Eagle, you want Skill mode's quick start and its ready-made task flows, and Eagle's previews and plugins matter to you.

Choose refern's Local API and MCP server if you want the connection built in, written access levels, no file deletion from disk, a change list with undo, Linux support, or a library that keeps your existing folders in place. For the full app comparison, read refern vs Eagle.

Source notes

Eagle facts were checked against Eagle's MCP / Skill plugin post on October 11, 2026, and against refern's June 2026 Eagle research, which cites the Eagle Plugin Center, Eagle store, and Eagle Linux support page.

refern facts were checked against the refern 1.10 Local API reference and the agent guide the app serves at /llms.txt while the API is on. No speed or reliability test of either connection is presented on this page.