yarr

# yarr

Self-hosted media fleet operations across Sonarr, Radarr, Plex, and related apps over MCP and CLI.

If you run Claude Code, Codex, or Gemini CLI against a self-hosted media stack,
`yarr` gives an agent one consistent way to query and control all of it instead
of eleven different ad hoc integrations. It is an upstream-client MCP server:
it does not replace those applications or mirror every REST endpoint as a web
UI. Its job is to provide one consistent tool surface for agents and one
equivalent CLI surface for operators.

**Not for:** a general-purpose REST gateway to arbitrary services, or a
scheduler/automation engine in its own right. `yarr` only talks to the service
kinds it knows about, and only does what you or your agent ask it to do.

## Contents

- [Naming](#naming)
- [Capabilities And Boundaries](#capabilities-and-boundaries)
- [Install](#install)
- [Unraid Plugin](#unraid-plugin)
- [Quickstart](#quickstart)
- [Client Configuration](#client-configuration)
- [Runtime Surfaces](#runtime-surfaces)
- [MCP Tool Reference](#mcp-tool-reference)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [Authentication](#authentication)
- [Safety And Trust Model](#safety-and-trust-model)
- [Architecture](#architecture)
- [Distribution Contract](#distribution-contract)
- [Development](#development)
- [Verification](#verification)
- [Deployment](#deployment)
- [Troubleshooting](#troubleshooting)
- [Related Servers](#related-servers)
- [Documentation](#documentation)
- [License](#license)

## Naming

This repository is published at `github.com/dinglebear-ai/yarr`.

The Rust package and installed binary are both `yarr`. The npm launcher package
is `yarr-mcp` because the shorter `yarr` name is occupied on npm; installing the
launcher still gives you a `yarr` command. The MCP registry name is
`ai.dinglebear/yarr`, and Docker images use `ghcr.io/dinglebear-ai/yarr`.
Production Compose deployments select that image by immutable manifest digest.

Plugin naming is intentionally split:

- `yarr` is the full MCP server plugin. It launches the repository-coupled
  `@dinglebear/yarr` npm package over stdio and includes every per-service fallback
  skill; it does not commit a platform-specific binary.
- `sonarr`, `radarr`, `prowlarr`, `overseerr`, `sabnzbd`, `qbittorrent`, `plex`,
  `jellyfin`, `tautulli`, `tracearr`, and `bazarr` are skills-only plugins with
  no MCP server and no bundled binary.

## Capabilities And Boundaries

`yarr` wraps a configured media automation fleet through one action-dispatched
service layer. The same implementation backs MCP and CLI calls, so behavior
does not drift between "agent used the tool" and "operator ran the command."

Primary capabilities:

- Fleet status checks across the configured services.
- Credentialed upstream API passthrough for known service kinds.
- Table-driven OpenAPI operation metadata for Sonarr, Radarr, Prowlarr,
  Overseerr, Jellyfin, and Plex. The executor preserves the declared parameter,
  request-media, and successful-response transport contract; unsupported rows
  are excluded and listed in the generated
  [capability matrix](https://github.com/dinglebear-ai/yarr/blob/main/docs/TOOLS_ACTIONS_ENDPOINTS.md#generated-operations-spec-backed-services).
- Curated commands for SABnzbd, qBittorrent, Tautulli, Bazarr, and Tracearr,
  whose upstreams do not ship usable machine-readable specs.
- Code Mode over MCP for multi-step media automation scripts.
- Snippet storage and execution for repeatable Code Mode workflows.
- Skills-only direct-HTTP plugin fallbacks for each individual service.

Boundaries:

- `yarr` does not store or schedule media jobs on its own.
- It does not expose a local REST action API or embedded web UI.
- It does not accept arbitrary unknown service kinds.
- MCP callers never provide credentials, tokens, keys, or secrets as action
  arguments. Credentials come from environment variables, config files, or
  strict per-service plugin config JSON.

## Install

The native release installer is the safest default because it verifies the
release archive and SHA-256 before installing `yarr` into `~/.local/bin`:

```bash
curl -fsSL https://raw.githubusercontent.com/dinglebear-ai/yarr/main/install.sh | bash
yarr --version
```

The npm launcher is a coupled distribution, not an alias for whatever version
happens to be tagged `latest`. Verify the exact release version exists on npm
before using it:

```bash
YARR_VERSION=2.1.0
npm view "@dinglebear/yarr@${YARR_VERSION}" version
npx -y "@dinglebear/yarr@${YARR_VERSION}" mcp
# Or, after the same availability check:
npm i -g "@dinglebear/yarr@${YARR_VERSION}"
```

Never use an unpinned `npx @dinglebear/yarr` or `@latest` in an MCP manifest: npm may
still point at an older launcher after a partial release. At the time of this
documentation refresh, GitHub release `v2.1.0` is public but
`@dinglebear/yarr@2.1.0` is not yet available on npm; recovery is tracked in
[issue #80](https://github.com/dinglebear-ai/yarr/issues/80). Use the native
installer, a verified release archive, a source build, or the independent
Unraid package until the exact npm version resolves.

## Unraid Plugin

The coordinated Unraid distribution lives under
[`unraid-plugin/`](https://github.com/dinglebear-ai/yarr/tree/main/unraid-plugin). It combines the classic `.plg`
installer and privileged service lifecycle, an external NestJS GraphQL
extension, and Vue settings/dashboard custom elements.

Install the plugin URL from Unraid's **Plugins > Install Plugin** page:

```text
https://raw.githubusercontent.com/dinglebear-ai/yarr/main/unraid-plugin/yarr.plg
```

Fresh installs bind Yarr to loopback. LAN or custom-address binding is rejected
until authentication is configured; Tailscale Serve is the supported
tailnet-only option. Service credentials stay in server-side boot
configuration and are never returned to the browser. See the
[Unraid operator and release guide](https://github.com/dinglebear-ai/yarr/blob/main/unraid-plugin/README.md) for persistence,
discovery, updates, rollback, uninstall retention, troubleshooting, and
release gates.

## Quickstart

The first-screen 30-second path is:

```bash
export YARR_SERVICES=sonarr
export YARR_SONARR_URL=http://127.0.0.1:8989
export YARR_SONARR_API_KEY=...

yarr sonarr status
yarr mcp
```

Then point an MCP client at the stdio command:

```json
{
  "mcpServers": {
    "yarr": {
      "command": "yarr",
      "args": ["mcp"],
      "env": {
        "YARR_SERVICES": "sonarr",
        "YARR_SONARR_URL": "http://127.0.0.1:8989",
        "YARR_SONARR_API_KEY": "${YARR_SONARR_API_KEY}"
      }
    }
  }
}
```

For Claude Code plugin installs, use the marketplace commands inside a Claude
Code chat session, not in a shell:

```text
/plugin marketplace add dinglebear-ai/yarr
/plugin install yarr@yarr
```

The full plugin starts the exact launcher pinned in its manifest. Confirm that
version exists before installing or debugging the plugin:

```bash
npm view @dinglebear/yarr@2.1.0 version
```

Until issue #80 is resolved, the full plugin cannot start from npm. The
service-specific skills-only plugins do not depend on that launcher and remain
available for direct upstream workflows.

Install one skills-only plugin when you want direct service scripts without the
MCP server:

```text
/plugin install sonarr@yarr
/plugin install plex@yarr
```

## Client Configuration

### stdio

stdio is the preferred local MCP transport. It starts `yarr mcp` on demand and
does not require binding a local HTTP port.

```json
{
  "mcpServers": {
    "yarr": {
      "command": "yarr",
      "args": ["mcp"],
      "env": {
        "RUST_LOG": "info,yarr=debug"
      }
    }
  }
}
```

### Streamable HTTP

Run a persistent server when several clients or machines should share one MCP
endpoint:

```bash
YARR_MCP_TOKEN=change-me yarr serve
```

```json
{
  "mcpServers": {
    "yarr": {
      "url": "http://127.0.0.1:40070/mcp",
      "headers": {
        "Authorization": "Bearer ${YARR_MCP_TOKEN}"
      }
    }
  }
}
```

HTTP MCP initialization smoke call:

```bash
curl --fail http://127.0.0.1:40070/mcp \
  -H "Authorization: Bearer $YARR_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-smoke","version":"1"}}}'
```

Use an MCP client such as mcporter for session-aware `tools/list` and Code Mode
calls; a raw one-shot `tools/call` is not a complete MCP session.

## Runtime Surfaces

| Surface | Status | Purpose |
|---|---:|---|
| MCP | Required | One default `yarr` Code Mode tool over the whole fleet |
| CLI | Required | Scriptable parity surface for debugging and automation |
| REST | Not shipped | Upstream-client servers do not expose a local REST action API |
| Web | Core: not shipped | The core server has no embedded UI; the classic Unraid distribution ships a separate settings/dashboard web surface |

Set `YARR_MCP_TOOL_MODE=flat` to advertise one action-dispatched MCP tool per
configured service instead of the single Code Mode tool. That mode is useful
behind a gateway such as Labby that already provides its own discovery and
sandbox layer. `codemode` is the default and the right choice for standalone
MCP clients.

## MCP Tool Reference

By default, MCP exposes one tool named `yarr`.

| Field | Type | Required | Notes |
|---|---|---:|---|
| `code` | string | yes | JavaScript async arrow function executed in the in-process Code Mode sandbox |

Inside Code Mode, scripts can use:

- Per-service callables such as `sonarr.get_series()`,
  `radarr.post_movie({ body })`, `prowlarr.get_indexer()`, and
  `plex.get_sessions()`.
- Curated commands such as `qbittorrent.download_queue()` and
  `tautulli.stats_activity()`.
- Raw passthrough helpers at `api.<service>.get/post/put/delete(path, body)`.
- `callTool(action, params)` for the und