# mcp-arr-lite

[![GHCR](https://img.shields.io/badge/GHCR-ghcr.io/cuti27/mcp--arr--lite-blue)](https://github.com/cuti27/mcp-arr-lite/pkgs/container/mcp-arr-lite)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

Lightweight [MCP](https://modelcontextprotocol.io) server for **Radarr** and **Sonarr** with a small set of granular, purpose-built tools. Unofficial project.

## Why this project?

General "arr" MCP servers (like `Knuckles-Team/arr-mcp`) auto-generate **thousands** of tools from the Arr API and hand the whole surface to the LLM. `mcp-arr-lite` is the opposite:

- **Granular tools**: exactly the operations needed for the "can you grab X for me?" flow — lookup, add, search releases, grab — no admin/config noise.
- **Preferred-indexer logic**: search tools default to the indexer with the lowest numeric priority, deterministic instead of prompt-dependent.
- **HITL-friendly**: read-only tools (lookup, list indexers) can be auto-approved; add/search/grab require explicit user approval.
- **Dual transport**: stdio (npx) and HTTP (Docker).

### Comparison with Knuckles-Team/arr-mcp

| Aspect | arr-mcp | mcp-arr-lite |
|---|---|---|
| Tool surface | 1123 generated tools | 9 hand-written tools |
| Preferred indexer | Prompt-dependent | Coded into search tools |
| Apps | 6+ Arr apps | Radarr + Sonarr |
| Transports | stdio | stdio + HTTP |
| Focus | Whole API | Add & download flow |

## Tools

| Tool | Read-only | Description |
|---|---|---|
| `radarr_lookup` / `sonarr_lookup` | ✅ | Search a movie/series by title, returns name + poster URL |
| `list_indexers` | ✅ | List indexers for an app, marking the preferred one |
| `radarr_add` / `sonarr_add` | ❌ | Add a movie/series (optionally trigger search) |
| `radarr_search_releases` / `sonarr_search_releases` | ❌ | Search releases, defaulting to the preferred indexer |
| `radarr_grab` / `sonarr_grab` | ❌ | Start downloading a release |

## Requirements

- Node.js >= 20 (npx) or Docker (container)
- Radarr and/or Sonarr with an API key

## Installation

### Docker Compose (recommended)

```yaml
services:
  arr-mcp:
    image: ghcr.io/cuti27/mcp-arr-lite:latest
    restart: unless-stopped
    environment:
      - RADARR_URL=http://radarr:7878
      - RADARR_API_KEY=your-radarr-api-key
      - SONARR_URL=http://sonarr:8989
      - SONARR_API_KEY=your-sonarr-api-key
      - MCP_TRANSPORT=http
      - MCP_AUTH_TOKEN=your-secure-token-here
      - PORT=3000
      - HOST=0.0.0.0
      - LOG_LEVEL=info
```

Only configure the apps you use — Radarr and Sonarr are both optional at startup; tools for an unconfigured app will return an error.

### stdio (npx)

```bash
RADARR_URL=http://radarr:7878 \
RADARR_API_KEY=... \
SONARR_URL=http://sonarr:8989 \
SONARR_API_KEY=... \
MCP_TRANSPORT=stdio \
npx -y @cuti27/mcp-arr-lite
```

## Environment variables

See [.env.example](./.env.example). Required per app: `RADARR_URL` + `RADARR_API_KEY`, `SONARR_URL` + `SONARR_API_KEY`. `MCP_AUTH_TOKEN` is required when `MCP_TRANSPORT=http`.

## Security

- HTTP transport enforces bearer auth, rate limiting (60 req/min/IP) and a 1 MB body limit.
- API keys are redacted from logs.
- Only run the HTTP transport with `MCP_AUTH_TOKEN` set and behind a TLS-terminating reverse proxy.

## License

MIT