{"id":"b2caae99-fcf3-401f-ae8b-c543c674c310","slug":"namarr","kind":"mcp","name":"namarr","summary":"Self-hosted media renamer for movies, series and anime. FileBot-style matching against TMDB, TheTVDB, TVmaze and AniDB, ReNamer-style rules for photos and music, naming formats for Plex, Jellyfin, Emb","owner":"firsttris","repoUrl":"https://github.com/firsttris/namarr","license":"AGPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-01T06:19:51.000Z","addedAt":"2026-10-21T18:12:09.232Z","logoUrl":"https://avatars.githubusercontent.com/u/1709260?u=8f3ec6e27611e361be75876b9043251886a2288b&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","design-media","files-documents"],"tags":["anidb","filebot","homelab","renamer","self-hosted","tmdb","tvdb","anime"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T21:30:22.276Z","sample":false,"url":"https://conduits.dev/tools/namarr","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"

namarr

\n\n
\n\n\"namarr:\n\n**The self-hosted renamer for movies, series and anime: a FileBot alternative for your home server.**
\nFileBot-style media matching and ReNamer-style rules in one web UI, in a Docker container.\nEvery change starts as a preview, and every change can be undone.\n\n[![CI](https://github.com/firsttris/namarr/actions/workflows/ci.yml/badge.svg)](https://github.com/firsttris/namarr/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/firsttris/namarr?logo=github&label=release)](https://github.com/firsttris/namarr/releases/latest)\n[![Docker Pulls](https://img.shields.io/docker/pulls/tristanteu/namarr?logo=docker&logoColor=white)](https://hub.docker.com/r/tristanteu/namarr)\n[![Image Size](https://img.shields.io/docker/image-size/tristanteu/namarr/latest?logo=docker&logoColor=white&label=image)](https://hub.docker.com/r/tristanteu/namarr)\n[![Platforms](https://img.shields.io/badge/platform-amd64%20%7C%20arm64-lightgrey)](https://hub.docker.com/r/tristanteu/namarr/tags)\n[![Bun](https://img.shields.io/badge/built%20with-Bun-fbf0df?logo=bun&logoColor=black)](https://bun.sh/)\n[![Docs](https://img.shields.io/badge/docs-firsttris.github.io%2Fnamarr-d9862e?logo=materialformkdocs&logoColor=white)](https://firsttris.github.io/namarr/)\n[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n\n[Features](#-features) •\n[Metadata](#-metadata-sources) •\n[Quick start](#-quick-start) •\n[AI agents](#-ai-agents) •\n[Documentation](https://firsttris.github.io/namarr/) •\n[Contributing](#-contributing)\n\n\"namarr\n\n
\n\n## 💡 How it works\n\n1. **Point it at a folder**: downloads, an old collection, photos or music.\n2. **Check the preview**: namarr matches every file against TMDB, TheTVDB, TVmaze or AniDB (or\n applies your rules) and shows old → new. Nothing moves yet.\n3. **Rename**, and undo it any time, per file or per job.\n\nOne container for your home server: FileBot-style matching for movies, series and anime,\nReNamer-style rules for everything else. Names come out in the format Plex, Jellyfin, Emby or Kodi\nexpect, or in your own.\n\n## ✨ Features\n\n| | |\n|---|---|\n| 🎬 **Movies, series, anime** | Matching against TMDB, TheTVDB, TVmaze and AniDB · IDs in folder names (`{tmdb-1399}`, `[tvdbid-72073]`) · ffprobe for names without resolution or codec |\n| ✏️ **Rules for everything else** | 16 ReNamer-style rules (replace, regex, numbering, clean up …) · photos by EXIF date · music by tags · rule sets as YAML |\n| 🧩 **Naming formats** | Template language with live example · built in: Plex, Jellyfin, Emby, Kodi · own formats per kind · **detect the format of your existing library** |\n| 🔍 **Preview & undo** | Test mode by default · diff view, keyboard control · conflicts incl. *keep better* (resolution, HDR, codecs, audio) · undo per file, job or point in time |\n| 🤖 **Automation** | Watch folders that wait for finished downloads · inbox for uncertain matches · hook for qBittorrent, SABnzbd, NZBGet · MCP server for AI agents |\n| 📚 **Libraries** | One default folder each for movies and series · move, copy or rename in place · folder browser for every path |\n| 🔔 **After a job** | Library refresh for Jellyfin, Emby, Plex · notifications via ntfy, Gotify, Telegram, Discord, webhook |\n| 🌍 **UI** | English and German, including every server message |\n\n## 🗂️ Metadata sources\n\n| Source | Movies | Series | Anime | Access |\n|---|:---:|:---:|:---:|---|\n| **TMDB** | ✅ | ✅ | ✅ | your own API key |\n| **TheTVDB** | ✅ | ✅ | ✅ | API key, plus PIN for a user-supported key |\n| **TVmaze** | | ✅ | | none, free |\n| **AniDB** | | | ✅ | registered client |\n\nSeries and movies can come from different sources, and every watch folder can pick its own series\nsource, for example AniDB for an anime folder. Details: [Metadata sources](https://firsttris.github.io/namarr/metadata.html).\n\n## 🐳 Quick start\n\n```bash\nmkdir namarr && cd namarr\ncurl -o compose.yml https://raw.githubusercontent.com/firsttris/namarr/main/docker/compose.example.yml\n# set NAMARR_TOKEN and your media mount, then\ndocker compose up -d\n```\n\nOpen **http://localhost:8420**, sign in with your token, then under *Settings* add your\n[folders](https://firsttris.github.io/namarr/installation.html#folders-and-libraries) (`/data`, or your download, movie and series\nmounts) and a TMDB API key, or set up one of the [other sources](https://firsttris.github.io/namarr/metadata.html).\n\n
\ndocker run\n\n```bash\ndocker run -d --name namarr --restart unless-stopped \\\n -p 8420:8420 \\\n -e PUID=1000 -e PGID=1000 \\\n -e NAMARR_TOKEN=\"$(openssl rand -hex 24)\" \\\n -v ./config:/config \\\n -v /mnt/data:/data \\\n tristanteu/namarr:latest\n```\n\n
\n\n
\nPodman Quadlet\n\n```bash\nmkdir -p ~/.config/containers/systemd ~/namarr/config\ncurl -o ~/.config/containers/systemd/namarr.container https://raw.githubusercontent.com/firsttris/namarr/main/docker/quadlet/namarr.container\n# adjust /mnt/data in namarr.container, then\nprintf 'a-long-token' | podman secret create namarr-token -\nsystemctl --user daemon-reload && systemctl --user start namarr\n```\n\n
\n\n
\nUnraid\n\nUse the template in [`docker/unraid/namarr.xml`](docker/unraid/namarr.xml).\n\n
\n\n| Volume | Content |\n|---|---|\n| `/config` | SQLite database |\n| `/data` | your downloads and your library (or one mount each, see the installation guide) |\n\nEnvironment variables, image tags, updates and the API are in the\n[installation guide](https://firsttris.github.io/namarr/installation.html).\n\n## 🤖 AI agents\n\nnamarr is an MCP server: an agent such as Claude Code previews, corrects, renames and undoes like you do\nin the workbench. Nothing moves without an explicit `execute_job`, and `NAMARR_MCP=readonly` leaves\nout every tool that changes files.\n\n```bash\nclaude mcp add --transport http namarr http://localhost:8420/api/mcp --header \"Authorization: Bearer $NAMARR_TOKEN\"\n```\n\nTools and setup for other clients: [AI agents (MCP)](https://firsttris.github.io/namarr/automation.html#ai-agents-mcp).\n\n## 📸 Screenshots\n\n
\n\"namarr\n
\n\n## 📚 Documentation\n\nThe full documentation is a website with search: **[firsttris.github.io/namarr](https://firsttris.github.io/namarr/)**.\nThe same pages are in [`docs/`](docs/) here on GitHub.\n\n| | |\n|---|---|\n| [Installation](https://firsttris.github.io/namarr/installation.html) | Compose, docker run, Quadlet, Unraid, folders, environment variables, image tags, updates and backup, health and events |\n| [Workbench](https://firsttris.github.io/namarr/workbench.html) | preview, actions, conflicts and *keep better*, undo, template language, naming formats and detecting them from a library, rules |\n| [Automation](https://firsttris.github.io/namarr/automation.html) | watch folders, inbox, download client hook, AI agents (MCP), library refresh, notifications |\n| [Metadata sources](https://firsttris.github.io/namarr/metadata.html) | TMDB, TheTVDB, TVmaze, AniDB, IDs in folder names, languages, episode order |\n| [Development](https://firsttris.github.io/namarr/development.html) | setup, checks, architecture, tests, parser corpus, roadmap |\n\n## 🛠️ Development\n\nRequires [Bun](https://bun.sh/) 1.4.\n\n```bash\ngit clone https://github.com/firsttris/namarr\ncd namarr\nbun install\nNAMARR_DEMO=1 bun run dev # http://localhost:8420 with an offline demo catalog\n```\n\n**Stack**: Bun, TanStack Start (React, server functions), TanStack Query and Virtual, Tailwind,\nSQLite with Drizzle, Vitest and Playwright. More in [Development](https://firsttris.github.io/namarr/development.html).\n\n## 🤝 Contributing\n\nA release name that namarr parses wrong is the most useful issue there is: add it to\n`packages/core/test/corpus/releases.yaml` or paste it into an issue. Pull requests are welcome; please\nrun `bun run lint`, `bun run typecheck` and `bun run test` before opening one.\n\n---\n\n
\n\n⭐ Like namarr? A [star on GitHub](https://github.com/firsttris/namarr) helps others find it.
\n🐛 [Report a bug](https://github.com/firsttris/namarr/issues/new) · 💡 [Request a feature](https://github.com/firsttris/namarr/issues/new)\n\nLicense: AGPL-3.0 · © Tristan Teufel and contributors
\nChanged versions you pass on or run for others must offer their source code under the AGPL; a commercial license without these obligations is available via teufel-it.de.
\nnamarr is not affiliated with TMDB, TheTVDB, TVmaze or AniDB.
\nThis product uses the TMDB API but is not endorsed or certified by TMDB.\n\n
\n"}