embyfin-mcp

An MCP server that finds what is wrong in an Emby or Jellyfin library and helps fix it, from Claude Code, Claude Desktop or any other MCP client.

Detection is code, correction is judgment. The server runs cheap, exact checks over the whole library and returns short worklists. The model reasons only about what they flag.

Install

brew install katbyte/tap/embyfin-mcp
# or
go install github.com/katbyte/embyfin-mcp@latest

A Docker image is published at ghcr.io/katbyte/embyfin-mcp. Tested against Emby 4.10 and Jellyfin 12.2.

Quick start

Make an API key in the server's dashboard, then put three settings in ~/.embyfin-mcp:

BACKEND=jellyfin
SERVER=http://nas:8096
TOKEN=...

Check that it connects, and register it with Claude Code:

embyfin-mcp info
claude mcp add embyfin -e EMBYFIN_TOOLSETS=curation -- embyfin-mcp serve

That loads the audits and everything that fixes what they find. Without EMBYFIN_TOOLSETS it loads six read-only tools.

The audits

Each audit checks a whole library for one thing that goes wrong. Each name links to its full rules.

| Audit | What it catches | |---|---| | audit_all | Runs the audits in one call and counts what each found. Start here. | | audit_missing_metadata | Items with no match, no poster or no plot. Fix with item_identify, item_artwork_set or item_refresh. | | audit_file_path | Files and folders named for another title, year or episode than the server holds. Fix with item_identify or item_edit, or rename the file. | | audit_duplicates | The same film or show held as two entries. quality_compare says which copy is better. | | audit_multiple_versions | One entry made of several files, such as a 4K and a 1080p copy. quality_compare says which is better. | | audit_runtime | Runtimes nothing can have: under 2 minutes, or 12 hours and over. Replace the file, or remove it with item_delete. | | audit_quality | Copies worth replacing: low resolution, an old format or a low bitrate. quality_compare weighs two copies. | | audit_missing_episodes | Episodes and seasons a series is missing. show_missing checks one series. | | audit_duplicate_episodes | One episode filed under two numbers in a season. item_delete removes the copy to go. | | audit_spelling | Genres, tags and studios spelled more than one way. Fix with metadata_rename. | | audit_whitespace | Stray spaces in names, tags and file names. Fix with item_edit or metadata_rename. | | audit_language | What has, or lacks, audio or subtitles in a language. item_subtitle_download fetches subtitles. | | audit_unwatched | Films or series nobody has watched: what to archive, remove with item_delete, or recommend with a playlist or collection. | | audit_disc_folders | A disc copied in as loose files, which the server reads as many films. Remux the feature to one file, then library_scan. | | audit_previews | Missing or damaged preview thumbnails, on Emby. Fix with item_previews_regenerate. | | audit_anime_ids | Anime whose ids disagree with the community Anime-Lists. Fix a wrong match with item_identify. | | audit_provider | Ids and runtimes that disagree with TMDB. Fix a wrong match with item_identify. Needs a TMDB key. | | audit_orphans | Items a removed library left behind. Fix with item_orphans_delete. |

The tools

There are 92 tools. Only core loads by default, because every tool's description takes room in the client's context. Load what the job needs with EMBYFIN_TOOLSETS.

| Toolset | For | Tools | |---|---|---| | core | Finding libraries and items; always loaded | 6 | | curation | The audits, and everything that fixes what they find | 39 | | watching | Watch history, what is next, marking things watched | 8 | | organise | Playlists and collections | 10 | | remote | What is playing, and controlling it | 4 | | admin | Libraries, scans, tasks, logs, accounts and deleting files | 25 | | all | Everything | 92 |

Three more settings matter early:

• EMBYFIN_READ_ONLY loads only the tools that change nothing.
• EMBYFIN_ENABLE_DELETE loads the tools that delete. It is off by default, and nothing deleted can be brought back.
• EMBYFIN_TMDB_TOKEN adds the checks that compare with TMDB.

More

• The audits: each audit's full rules, edge cases and options.
• The tools: every tool, by what it acts on, and how deleting works.
• Choosing which tools load: toolsets, families, allow and deny lists.
• Configuration: every setting, the settings file, and two servers at once.
• Running it as a service: over HTTP, and in Docker.
• A typical curation session: the audits and their fixes, in order.
• Cleaning up after a removed library: removing what it left behind.
• Using the Go clients on their own: typed clients for the Emby, Jellyfin and TMDB APIs, with no MCP in them.
• Development: building, the tests and the fixtures.
• Contributing: what a change needs, and how releases are cut.

How this is built

• I set the design, the scope and the audit rules, and I decide what stays.
• Every tool must have a live test against a real Emby and a real Jellyfin in Docker. CI fails if a tool has none.
• The generated Go clients are checked another way. Every operation must have a method, and a sweep calls every read against the live servers. Every write embyfin's own code sends must be reached by a live test, and CI fails if one is not.
• CI lints with golangci-lint, actionlint, yamllint, ShellCheck, typos and markdownlint. golangci-lint covers every Go file, the generated clients and the live tests included.
• For security it runs CodeQL, govulncheck, zizmor on the workflows, and a Trivy scan of the built binary.