About Sonarr MCP Server
Sonarr MCP Server connects MCP clients to Sonarr, letting them inspect series and episodes, review activity, and add series through a mix of read-only and write tools.
Key features
- 01Search TV series
- 02Find series episodes
- 03View logs and download history
- 04List upcoming episodes
- 05Add series
- 06Read series and episode resources
Use cases
- 01Find a series and inspect its episodes
- 02Check recent downloads or upcoming episodes
- 03Add a series to Sonarr
- 04Retrieve quality profiles and definitions
MCP support
Exposes Sonarr search, episode, log, download, calendar, and series-management tools to MCP clients, along with series, episode, and quality-profile resources.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
6Saved tool list · updated 3w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| tags | array | No | Optional tag IDs |
| title | string | Yes | The title of the show to add |
| tvdbId | integer | Yes | The TVDB ID of the show to add |
| monitored | boolean | No | Whether the series is monitored |
| addOptions | object | No | |
| addOptions.searchForMissingEpisodes | boolean | No | |
| seasonFolder | boolean | No | Whether to use season folders |
| rootFolderPath | string | No | The folder where Sonarr stores the series |
| qualityProfileId | integer | No | The Sonarr quality profile ID to use |
| languageProfileId | integer | No | Optional language profile ID |
Details
From the project READMESonarr MCP Server
This is a Model Context Protocol (MCP) server for accessing Sonarr. It provides a set of tools for interacting with Sonarr programmatically.
Prerequisites
- Node.js >= 20
- A running Sonarr instance (v3 or v4)
- Your Sonarr API key (found in Sonarr UI under Settings > General > API Key)
Tools
The following tools are available:
| Tool | Description | Read-only |
|---|---|---|
search-series | Search for a TV series by term | Yes |
find-episodes | Find episodes for a series | Yes |
get-logs | Get paginated logs from Sonarr | Yes |
list-recent-downloads | List recent download history | Yes |
list-upcoming-episodes | List upcoming episodes from the calendar | Yes |
add-series | Add a series to Sonarr | No |
Example tool calls
Search for a series:
{ "term": "Severance" }
Find episodes:
{ "seriesId": 123, "seasonNumber": 1 }
Add a series:
{
"title": "Severance",
"tvdbId": 371980,
"qualityProfileId": 1,
"rootFolderPath": "/tv"
}
Resources
The following resources are available:
sonarr://series/{id}- Retrieve information about a specific series by IDsonarr://episode/{id}- Retrieve information about a specific episode by IDsonarr://quality-profile- List quality profiles configured in Sonarrsonarr://quality-definition- List quality definitions used by Sonarr
Configuration
Create a .env file or set environment variables:
SONARR_URL=http://localhost:8989
SONARR_API_KEY=your-api-key-here
Usage
With Claude Desktop / MCP Clients
Add this server to your MCP config:
{
"mcpServers": {
"sonarr": {
"command": "npx",
"args": ["-y", "sonarr-mcp"],
"env": {
"SONARR_URL": "http://localhost:8989",
"SONARR_API_KEY": "<your-sonarr-api-key>"
}
}
}
}
Local Development
npm install
npm run build
npm run test
npm run lint
Run locally with stdio transport:
SONARR_URL=http://localhost:8989 SONARR_API_KEY=xxx npm start
Security
- Keep your
SONARR_API_KEYprivate. Treat it like a password. - Do not commit
.envfiles containing your API key. - The server communicates with Sonarr over HTTP(S). Use HTTPS when exposing Sonarr externally.
Troubleshooting
| Issue | Possible Cause | Solution |
|---|---|---|
| "fetch failed" or connection errors | Wrong SONARR_URL | Verify the URL and that Sonarr is running |
| "Sonarr HTTP 401" | Invalid API key | Check your API key in Sonarr settings |
| "Invalid environment variables" | Missing required env vars | Set both SONARR_URL and SONARR_API_KEY |
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.