sonarr MCP server
Commit Nov 1, 2026Enables an AI assistant to audit and fix issues within a Sonarr TV library using specialized detection tools.
Also known as katbyte/sonarr-mcp
- Stars
- 0
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 1, 2026
- License
- GPL-3.0
What is sonarr MCP?
sonarr enables an AI assistant to audit and fix issues within a Sonarr TV library using specialized detection tools. It exposes 6 tools, such as core, library, curation.
Summary generated from the project's README
About sonarr MCP server
Auditing and repairing a Sonarr TV library through an AI assistant is what this server enables. It provides a bridge between LLM clients like Claude Desktop and your Sonarr instance, allowing an assistant to identify library discrepancies and execute corrective actions. The system operates by running specific audits that detect issues such as missing episodes, incorrect file naming, or quality mismatches, then presenting the assistant with the appropriate tools to fix them.
Users can deploy this as a local process or an HTTP server. Setup requires a Sonarr server address and an API token provided via environment variables. To manage token usage and complexity, the server uses toolsets like core, library, curation, admin, and settings. This modular approach ensures that an assistant only loads the specific capabilities it needs for a task. Safety is prioritized through read-only modes and mandatory confirmations for any destructive actions or risky operations like server restarts.
What you can do with it
- 1Perform a full library auditAsk the assistant to run a comprehensive check across the entire library to find all existing issues.
- 2Fix missing television episodesIdentify episodes that have aired but are not in the library and use search tools to find them.
- 3Correct file naming inconsistenciesDetect files that do not follow the established naming conventions and trigger a rename process.
- 4Resolve download failuresFind downloads that failed in the last month and search for new releases to replace them.
Written from the project's README. Every use case is checked against a quote from it.
sonarr MCP tools 6
Detected from the READMEcorelibrarycurationadminsettingsall
Configuration
SONARR_SERVERSONARR_TOKENSONARR_TOOLSETS
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablekatbyte/sonarr-mcp is public and reachablegithub.com/katbyte/sonarr-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-01github.com/katbyte/sonarr-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubsonarr-mcp - a Sonarr MCP server, CLI and Go SDK
sonarr-mcp lets an AI assistant find what has gone wrong in a Sonarr library, and fix it.
Detection is code, correction is judgment. The server checks the whole library and hands back a short list of problems, each with the tool that fixes it. The assistant only has to decide what to do.
Install it, and register it with Claude Code:
go install github.com/katbyte/sonarr-mcp@latest
claude mcp add sonarr -e SONARR_SERVER=http://nas:8989 -e SONARR_TOKEN=... -e SONARR_TOOLSETS=curation -- sonarr-mcp serve
Then ask for audit_all. It says where the library needs work.
It is an MCP server, so Claude Desktop and any other MCP client work too.
The audits
There are 18, and audit_all runs them all. Each checks the whole library for one thing that goes wrong.
| audit | what it catches |
|---|---|
audit_all |
Runs every audit and gives the counts. Start here. |
audit_missing_episodes |
Episodes that aired and never arrived. Fix with episode_search or season_search. |
audit_no_files |
Series with no files at all, and why. Fix with series_search or import_apply. |
audit_cutoff_unmet |
Files below the quality their profile asks for. Fix with series_search. |
audit_stuck_downloads |
Downloads waiting on a person, and Sonarr's reason. Fix with import_apply or queue_remove. |
audit_failed_downloads |
Downloads that failed in the last 30 days, or went nowhere. Fix with release_search. |
audit_missing_files |
Files Sonarr lists that are gone from disk. Fix with series_rescan. |
audit_untracked_files |
Video files in a series folder that Sonarr does not track. Fix with import_apply. |
audit_unmapped_folders |
Folders on disk that are not a series in Sonarr. Fix with series_import. |
audit_missing_folders |
Series whose folder was moved, renamed or lost. Fix with series_edit and series_rescan. |
audit_naming |
Files not named the way Sonarr is set to name them. Fix with series_rename. |
audit_quality_mismatch |
Files recorded as one quality that are really another. Fix with file_edit. |
audit_runtime |
Files much shorter or longer than the episode. Fix with release_search. |
audit_language |
Files in the wrong language. Fix with file_edit or release_search. |
audit_monitoring |
Monitoring that will quietly miss new episodes. Fix with series_edit or season_monitor. |
audit_series_settings |
Series set up wrong, such as anime not marked as anime. Fix with series_edit. |
audit_profiles |
Profiles, tags and rules that nothing uses. Fix with tag_delete. |
audit_health |
Sonarr's own health warnings, and disks running low. |
audit_server |
No recent backup, an update waiting, errors in the log. Fix with backup_create. |
The rules behind each audit are in docs/audits.md.
What else is in the box
- 142 tools. Look through the library, search and grab, import and rename, change Sonarr's settings, and run backups and restarts. See docs/tools.md.
- Small by default. Six read-only tools load unless you ask for more.
- Careful by default. Nothing can be deleted until you turn deleting on, and each delete then waits to be confirmed.
- A Go client.
sdk/sonarrcovers all 239 operations of Sonarr's v3 API, and works on its own. See docs/sdk.md. - Tested against a real Sonarr. Every tool runs against Sonarr 4.0.20 in Docker. Searches really grab, and downloads really import.
Configuration
Set these as environment variables, as flags, or in a config file. Only the first two are required.
| Variable | Flag | What it does |
|---|---|---|
SONARR_SERVER |
--server |
Sonarr's address, such as http://nas:8989. |
SONARR_TOKEN |
--token |
Sonarr's API key, from Settings → General → Security. |
SONARR_TOOLSETS |
--toolsets |
Which groups of tools load. See Tools. |
SONARR_READ_ONLY |
--read-only |
Load only the tools that change nothing. |
SONARR_ENABLE_DELETE |
--enable-delete |
Load the tools that delete. |
SONARR_ALLOW_TOOLS |
--allow-tools |
Load these tools, by name. |
SONARR_DENY_TOOLS |
--deny-tools |
Never load these tools. |
SONARR_LISTEN |
--listen |
Serve over HTTP on this address. |
SONARR_AUTH_TOKEN |
--auth-token |
The token HTTP clients must send. |
SONARR_ALLOW_NO_AUTH |
--allow-no-auth |
Serve HTTP with no token, open to anyone who can reach it. |
SONARR_LOG |
How much to log: WARN (the default), INFO or TRACE. |
SONARR_URL and SONARR_API_KEY work too, since other Sonarr tools use those names.
A config file goes in ~/.sonarr-mcp, or in ./.sonarr-mcp for one project. Its names are the flags in capitals, with _ for - and without SONARR_ in front, such as ALLOW_TOOLS. A name it does not take stops the program, saying what to write instead:
SERVER=http://nas:8989
TOKEN=0123456789abcdef...
TOOLSETS=curation
Usage
Check the connection:
sonarr-mcp info
In a project's .mcp.json:
{
"mcpServers": {
"sonarr": {
"command": "sonarr-mcp",
"args": ["serve"],
"env": {
"SONARR_SERVER": "http://nas:8989",
"SONARR_TOKEN": "...",
"SONARR_TOOLSETS": "curation"
}
}
}
}
Over HTTP. sonarr-mcp serve --listen :8080 serves at /mcp, so one server can be shared between machines. It will not start without SONARR_AUTH_TOKEN, which clients send as a bearer token:
claude mcp add --transport http sonarr http://nas:8080/mcp --header "Authorization: Bearer $SONARR_AUTH_TOKEN"
In Docker. Each release publishes an image to ghcr.io/katbyte/sonarr-mcp, and docker-compose.yml runs it as an HTTP server. Set SONARR_SERVER and TZ in that file, then:
cp .env.example .env # fill in SONARR_TOKEN and SONARR_AUTH_TOKEN
docker compose up -d
Tools
Only core loads by default. Every tool the assistant is given takes room it could use to think, so load the groups a session needs.
| toolset | what it is for | tools | ~tokens |
|---|---|---|---|
core |
Find and read series, episodes and the queue. | 6 | 1,000 |
library |
Add shows and root folders. | 11 | 1,800 |
curation |
Every audit, and what fixes their findings. | 54 | 9,500 |
admin |
Health, logs, backups and restarts. | 26 | 3,500 |
settings |
Set Sonarr up: indexers, download clients, profiles, rules. | 54 | 10,400 |
all |
Everything. | 127 | 22,100 |
Counts include core, which always loads. The 15 tools that delete are extra, and load only with --enable-delete.
The guard rails:
- Read-only.
--read-onlyloads the 69 tools that change nothing. The rest are not there to be called. - Deletes. Without
confirm, a delete tool changes nothing and answers what it would delete. - Risky changes. A restart, a shutdown, restoring a backup and changing the host's settings wait for
confirmtoo. - Credentials. They can be set, and are never shown.
- Text from outside. Release names, plots and download client messages are cleaned of hidden characters and cut short.
More
- docs/audits.md: what each audit looks for, and every kind of problem it reports.
- docs/tools.md: every tool, and the rules they all follow.
- docs/toolsets.md: choosing which tools load, down to single tools.
- docs/curation.md: a typical session, one audit at a time.
- docs/sdk.md: using the Go client on its own, and how it is made.
- docs/development.md: building, the tests and the live suites.
- docs/ROADMAP.md: what is done and what is next.
- CONTRIBUTING.md: checking a change, and how releases go out.
sonarr MCP questions
What tools does sonarr MCP provide?
It exposes 6 tools, including core, library, curation, admin, settings.
Is it safe to use tools that delete files?
Yes, the server is careful by default; nothing can be deleted until you explicitly enable deleting, and each deletion requires confirmation.
Can I run this server in read-only mode?
Yes, you can use the --read-only flag to load only the tools that do not change any data.
How do I connect to my Sonarr instance?
You need to provide the SONARR_SERVER address and your SONARR_TOKEN API key via environment variables, flags, or a config file.