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 |