# Sonarr MCP Server

This is a [Model Context Protocol](https://modelcontextprotocol.org) (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:**
```json
{ "term": "Severance" }
```

**Find episodes:**
```json
{ "seriesId": 123, "seasonNumber": 1 }
```

**Add a series:**
```json
{
  "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:

```bash
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:

```json
{
  "mcpServers": {
    "sonarr": {
      "command": "npx",
      "args": ["-y", "sonarr-mcp"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "<your-sonarr-api-key>"
      }
    }
  }
}
```

### Local Development

```bash
npm install
npm run build
npm run test
npm run lint
```

Run locally with stdio transport:
```bash
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` |