# Sonarr (TV) MCP > Sonarr (TV) MCP Server handles your entire TV media library through chat commands. It lets you list series, add new shows via ID, track episode status, and delete physical files directly from your storage using any AI agent. ## Overview - **Category:** productivity - **Price:** Free - **Tags:** media-management, pvr, automation, rss-feeds, tv-shows, library-tracking ## Description Sonarr's got your back. Connect your AI agent to this server, and you get total command over your whole TV media library—no need to open up that clunky web interface. You control everything here, from deleting old files off your disk to managing what's sitting in the download queue. **Viewing Your Library Contents** Need to know what shows you're running? Use `list_series` to get a rundown of every show currently tracked on your setup. If you want deep info on one specific title, run `get_series` with its unique ID number. To see the full scope of episodes for any given series, `list_episodes` gives you a complete catalog of everything known about that show. For details on just one episode's metadata, `get_episode` takes an ID and spits out all the associated data. **Handling Episode Files** You got files taking up space? Use `delete_episode_file` to manually wipe a specific episode file off your local storage. You can also run `list_episode_files` to see every physical file saved for an entire series, helping you know exactly what's there before you delete it. To get the actual path and details of a finished episode file, use `get_episode_file`. When you need to adjust something about an existing show or episode—like marking it as monitored—you run `update_episode` for single titles, or `update_series` if you're changing metadata for the entire series. **Managing Your Download Queue and History** Is something stuck in the download line? Use `get_queue` to list every item waiting or processing right now. If an item is stalled or unnecessary, you can stop it and clear it with `delete_queue_item`. You always wanna keep track of what's been grabbed before; `get_history` shows a detailed log of all episodes that successfully imported into your library. **System Health and Setup** You gotta know if the system is actually talking to everything right. Run `get_health` to check Sonarr for any warnings or errors regarding connectivity status. For general machine info, like the installed version and configured paths, use `get_system_status`. If you need a full list of commands available on this server, run `list_commands`. To start a specific process—like initiating a series search or refreshing data—you just call `start_command`. **Adding and Deleting Series** Got a new show you wanna track? You use `add_series`, providing its unique identifier to get it into the library. If a show leaves your tracking list, run `delete_series` to remove the entire series entry from your monitored collection. ## Tools ### add_series Adds a new TV show series to the library using its identifier. ### delete_episode_file Removes a specific episode file from your local disk storage. ### delete_queue_item Stops and removes one item that is currently waiting in the download queue. ### delete_series Removes an entire series entry from your tracked library. ### get_episode_file Returns the file path and details for a specific, finished episode file. ### get_episode Retrieves all metadata for a single episode using its unique ID number. ### get_health Checks Sonarr for any warnings or errors regarding system connectivity. ### get_history Shows a log of all episodes that have been successfully grabbed and imported into the library. ### get_queue Lists every item currently waiting or processing in the download queue. ### get_series Retrieves all metadata for a specific series using its unique ID number. ### get_system_status Returns general system information, like the running version and configured paths. ### list_commands Lists all command types that are currently available to run against the server. ### list_episode_files Returns a list of all physical episode files saved for an entire series. ### list_episodes Gets a complete catalog of every known episode within a specific series. ### list_series Returns the names and details for every show currently tracked in your library. ### start_command Initiates a new, specific command like a series search or refresh process. ### update_episode Changes the status of an existing episode, such as marking it as monitored. ### update_series Updates metadata for a whole series, like changing its quality profile. ## Prompt Examples **Prompt:** ``` List all TV series in my Sonarr library. ``` **Response:** ``` I've retrieved your library. You have 12 series managed, including 'The Last of Us', 'Succession', and 'The Bear'. Would you like details on a specific one? ``` **Prompt:** ``` Check the current download queue and history. ``` **Response:** ``` Currently, there are 2 items in the queue: 'The Bear S02E01' (65% done) and 'Succession S04E10' (queued). Your history shows 5 successful imports today. ``` **Prompt:** ``` Get details for episode ID 1542. ``` **Response:** ``` Episode 1542 is 'Connor's Wedding' from 'Succession'. It is currently monitored and the file status is 'Downloaded'. ``` ## Capabilities ### View Library Contents List all series currently tracked in your media library or retrieve a specific show's details. ### Manage Episode Files Get file paths for a specific episode, list all files belonging to a series, or delete physical episode files from disk. ### Control Download Queue View every item waiting in the download queue (`get_queue`) and remove items that are stalled or unnecessary (`delete_queue_item`). ### Update Show Statuses Mark episodes as monitored, update an entire series entry, or add brand new series to your tracking list. ### Audit System Health Check Sonarr’s overall connectivity status (`get_system_status`) and access the download history of all past grabs and imports. ## Use Cases ### The Clean-up Crew You realize your storage drive is full of old, unused show files. Instead of manually browsing the directories and deleting things, you ask your agent to run `list_episode_files` for a series, verify the names, and then tell it to execute `delete_episode_file` on the junk entries. ### The Newbie Show A friend gives you a new show's name. You don't want to manually check if Sonarr tracks it. Your agent runs `add_series`, sends the necessary identifiers, and immediately gets the series added to your monitored library. ### The Stuck Download You know an important season is downloading but it seems frozen in the queue. You ask the agent to run `get_queue`. Seeing the status, you realize it's stuck and use `delete_queue_item` to remove it and restart the process cleanly. ### The Status Check You just started your workday. Before opening anything, you ask: 'What shows are currently monitored?' The agent runs `list_series`, giving you a quick overview of the whole library's status in seconds. ## Benefits - File Cleanup: Don't manually search for old files. Use `delete_episode_file` to delete specific episode files directly from the agent, freeing up disk space instantly. - Tracking Status: Need to know if a show is still being monitored? Run `get_series` or `list_episodes`. You get immediate status updates without opening any web dashboard. - Queue Management: Downloads stuck in limbo are common. Use `get_queue` to see what's running, and then use `delete_queue_item` to clear out stalled processes when you need them gone. - Zero Setup Effort: Forget remembering complex API calls or navigating deep menus. Just ask your agent: 'What series do I have?' and it runs `list_series` for you. - Audit Trail: Need proof of what was imported? Use `get_history`. It gives you a clear log of all episodes successfully added, which is better than digging through logs yourself. ## How It Works The bottom line is: You talk to your agent, and it talks directly to Sonarr for you. 1. Subscribe to this server, then provide your Sonarr URL and API Key. 2. Instruct your AI agent with a natural language request (e.g., 'List all my series'). 3. The agent calls the correct tool (`list_series`), fetches the data, and presents you with actionable results. ## Frequently Asked Questions **How do I list all series using Sonarr (TV) MCP Server?** Run `list_series`. This tool fetches and returns a complete catalog of every show currently tracked in your library, giving you an immediate overview. **Can I delete files with the Sonarr (TV) MCP Server? Which tool do I use?** Yes, use `delete_episode_file`. You need to provide the specific episode file's path or ID when calling this function. This deletes physical files from your disk. **What if my download is stuck? Can I check it with Sonarr (TV) MCP Server?** You can use `get_queue`. This tool shows everything waiting in the queue, and you can then run `delete_queue_item` to clear out anything that's stalled. **How do I find all episodes for a specific show?** Run `list_episodes`. This tool takes a Series ID and returns a complete list of every episode associated with that series in your library metadata. **How do I check for operational errors or warnings using the `get_health` tool?** It reports any system health warnings or errors found in your Sonarr installation. This is essential for troubleshooting, as it surfaces connectivity issues or configuration problems before they stop your media acquisition. **What steps do I take if I want to add a brand new TV series using the `add_series` tool?** The `add_series` tool creates the entry for a show in your library. You must provide identification details, like the TVDB ID or name, so Sonarr knows exactly what content you're tracking. **How do I get a complete inventory of physical episode files for a series using `list_episode_files`?** This tool returns all local file paths associated with an entire series. Use this when you need to audit your storage, confirm which episodes are on disk, or prepare for manual cleanup. **If I manually verify an episode's status, how do I update it using the `update_episode` tool?** The `update_episode` tool changes the monitored state of a specific show. This is useful after you've manually downloaded or confirmed an episode's availability outside Sonarr. **Can I add a new TV series to my library using this agent?** Yes! Use the `add_series` tool. You will need to provide the title, TVDB ID, and the root folder path where the files should be stored. **How do I check if Sonarr is running correctly or has any errors?** You can use the `get_health` tool to see any active health checks or `get_system_status` to retrieve general system information and version details. **Is it possible to see what is currently being downloaded?** Absolutely. Use the `get_queue` tool to list all items currently in the download queue, including their status and progress.