Sonarr MCP Server
About
It is an MCP (Model Context Protocol) server that provides a set of tools and resources for interacting with a Sonarr instance programmatically. It is designed for users who want to automate Sonarr TV series management through AI assistants or other MCP clients.
Details
- Author
- jbydeley
- GitHub stars
- 2
- Downloads
- 289
- Categories
- Other
Jump to
- Search for a TV series by term
- Find episodes for a series
- List upcoming episodes from calendar
- Add a series to Sonarr
- Retrieve series and episode details via resources
- List quality profiles and definitions
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Sonarr MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install the server via npx or by cloning the repository and building it locally. Configure it by setting the SONARR_URL and SONARR_API_KEY environment variables, then add it to your MCP client configuration (e.g., Claude Desktop). The server communicates using stdio transport.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"sonarr mcp server": {
"sonarr": {
"command": "npx",
"args": [
"-y",
"sonarr-mcp"
],
"env": {
"SONARR_URL": "http://localhost:8989",
"SONARR_API_KEY": ""
}
}
}
}
}McpServers
{
"sonarr": {
"command": "npx",
"args": [
"-y",
"sonarr-mcp"
],
"env": {
"SONARR_URL": "http://localhost:8989",
"SONARR_API_KEY": ""
}
}
}Sonarr 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 ID
- sonarr://episode/{id} - Retrieve information about a specific episode by ID
- sonarr://quality-profile - List quality profiles configured in Sonarr
- sonarr://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_KEY private. Treat it like a password.
- Do not commit .env files 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 |
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
