Metadata

name: seerr-cli
description: CLI for the Seerr media request management API. Search movies and TV shows, create and manage media requests, manage users, track issues, and administer a self-hosted Seerr instance. Use when asked to find, request, or manage media content, check what is trending, look up actors or collections, manage users, or check system status.
metadata: {"author":"electather","repo":"https://github.com/electather/seerr-cli","install":"Download the latest release archive from https://github.com/electather/seerr-cli/releases/latest, verify the SHA-256 checksum, and move the binary to a directory on PATH. A Docker image is also available at ghcr.io/electather/seerr-cli."}
primary_credential: SEERR_API_KEY
env: [{"name":"SEERR_SERVER","description":"Full URL of your Seerr instance (e.g. https://seerr.example.com)","required":true},{"name":"SEERR_API_KEY","description":"API key for authenticating with the Seerr server (primary credential)","required":true},{"name":"SEERR_MCP_TRANSPORT","description":"MCP server transport mode; \"stdio\" (default) or \"http\"","required":false},{"name":"SEERR_MCP_ADDR","description":"Listen address for the MCP HTTP server (default \":8811\")","required":false},{"name":"SEERR_MCP_AUTH_TOKEN","description":"Bearer token for MCP HTTP transport clients. When using HTTP transport, at least one of SEERR_MCP_AUTH_TOKEN, SEERR_MCP_ALLOW_API_KEY_QUERY_PARAM, or SEERR_MCP_NO_AUTH=true must be set. Not used for stdio transport.","required":false},{"name":"SEERR_MCP_NO_AUTH","description":"Set to \"true\" to disable all MCP HTTP authentication. Only use in trusted environments where the endpoint is access-controlled by other means.","required":false},{"name":"SEERR_MCP_ALLOW_API_KEY_QUERY_PARAM","description":"Set to \"true\" to accept the Seerr API key via the api_key query parameter in addition to the X-Api-Key header. Useful for clients that cannot send custom headers (e.g. claude.ai remote MCP). The MCP endpoint is always /mcp; append ?api_key=<key> to authenticate. HTTP transport only.","required":false},{"name":"SEERR_MCP_CORS","description":"Set to \"true\" to enable CORS headers for browser-based MCP clients (e.g. claude.ai)","required":false},{"name":"SEERR_MCP_TLS_CERT","description":"Path to a TLS certificate file for HTTPS on the MCP HTTP server","required":false},{"name":"SEERR_MCP_TLS_KEY","description":"Path to a TLS private-key file for HTTPS on the MCP HTTP server","required":false},{"name":"SEERR_MCP_LOG_FILE","description":"Path to a log file; required for stdio transport to capture logs without polluting stdout","required":false},{"name":"SEERR_MCP_LOG_LEVEL","description":"Log level for the MCP server; one of debug, info, warn, error (default \"info\")","required":false},{"name":"SEERR_MCP_LOG_FORMAT","description":"Log output format for the MCP server; \"text\" (default) or \"json\"","required":false}]

seerr-cli

CLI for interacting with a Seer media request management server.

Installation

Download the latest release archive and checksum file from the Releases page, verify, and install:

# Replace <os> and <arch> with your platform (linux/darwin, amd64/arm64)
curl -fsSL https://github.com/electather/seerr-cli/releases/latest/download/seerr-cli_<version>_<os>_<arch>.tar.gz -o seerr-cli.tar.gz
curl -fsSL https://github.com/electather/seerr-cli/releases/latest/download/seerr-cli_<version>_checksums.txt -o checksums.txt
grep seerr-cli_<version>_<os>_<arch>.tar.gz checksums.txt | sha256sum -c
tar -xzf seerr-cli.tar.gz
sudo mv seerr-cli /usr/local/bin/

Supports Linux and macOS (amd64 / arm64).

Docker

Run the MCP HTTP server in a container next to your Seerr instance:

# With Bearer token auth
docker run --rm \
  -e SEERR_SERVER=http://your-seerr-instance:5055 \
  -e SEERR_API_KEY=your-api-key \
  -e SEERR_MCP_AUTH_TOKEN=your-secret-token \
  -p 8811:8811 \
  ghcr.io/electather/seerr-cli:latest

MCP endpoint: http://localhost:8811/mcp — set Authorization: Bearer your-secret-token in your MCP client.

For clients that cannot send custom headers (e.g. claude.ai remote MCP), use query parameter transport:

docker run --rm \
  -e SEERR_SERVER=http://your-seerr-instance:5055 \
  -e SEERR_API_KEY=your-api-key \
  -e SEERR_MCP_ALLOW_API_KEY_QUERY_PARAM=true \
  -e SEERR_MCP_CORS=true \
  -p 8811:8811 \
  ghcr.io/electather/seerr-cli:latest

MCP endpoint: http://localhost:8811/mcp?api_key=your-api-key — no auth header required.

At least one of SEERR_MCP_AUTH_TOKEN, SEERR_MCP_ALLOW_API_KEY_QUERY_PARAM, or SEERR_MCP_NO_AUTH=true must be set for HTTP transport.

docker-compose deployment

Use the included docker-compose.yml to deploy alongside Seer:

SEERR_API_KEY=xxx SEERR_MCP_AUTH_TOKEN=secret docker compose up -d

The default SEERR_SERVER in the compose file points to http://seer:5055 (the Seerr service name). Override it if your Seerr instance is elsewhere.

Running CLI commands via Docker

Override the default CMD to run any CLI command:

docker run --rm \
  -e SEERR_SERVER=http://your-seerr-instance:5055 \
  -e SEERR_API_KEY=your-api-key \
  ghcr.io/electather/seerr-cli:latest \
  status system

Setup

seerr-cli config set --server https://your-seerr-instance.com --api-key YOUR_KEY
seerr-cli config show   # verify

Environment variables also work: SEERR_SERVER, SEERR_API_KEY.

Global Flags

-s, --server — Seerr server URL
-k, --api-key — API key
-v, --verbose — show request URLs and HTTP status codes
--config — path to config file (default ~/.seerr-cli.yaml)

Output

All commands return JSON. Pipe to jq for filtering. With --verbose, extra info (URL, HTTP status) is printed before the JSON.

Commands

Search & Discovery

Find movies, TV shows, and people:

seerr-cli search multi -q "The Matrix"              # search everything
seerr-cli search multi -q "Nolan" --page 2           # paginated results
seerr-cli search keyword -q "sci-fi"                 # TMDB keywords
seerr-cli search company -q "A24"                    # production companies
seerr-cli search trending                            # currently trending
seerr-cli search trending --time-window week          # weekly trending
seerr-cli search movies --genre 28                   # discover by genre
seerr-cli search movies --studio 7505                # by studio
seerr-cli search movies --sort-by popularity.desc    # custom sort
seerr-cli search tv --genre 18 --network 213         # TV by genre + network

Search results include a mediaType field (movie, tv, or person) and a TMDB id used by other commands.

If mediaInfo exists on a result, it's already tracked. mediaInfo.status values: 1=unknown, 2=pending, 3=processing, 4=partially available, 5=available.

Movie Details

seerr-cli movies get 157336                  # details by TMDB ID
seerr-cli movies ratings 157336              # ratings
seerr-cli movies ratings-combined 157336     # combined RT/IMDB ratings
seerr-cli movies recommendations 157336      # recommended movies
seerr-cli movies similar 157336              # similar movies

TV Show Details

seerr-cli tv get 72844                       # show details
seerr-cli tv ratings 72844                   # ratings
seerr-cli tv recommendations 72844           # recommendations
seerr-cli tv similar 72844                   # similar shows
seerr-cli tv season 72844 1                  # season details + episodes

Requesting Media

Create requests for movies or TV shows using their TMDB ID:

# Request a movie
seerr-cli request create --media-type movie --media-id 157336

# Request a TV show (all seasons)
seerr-cli request create --media-type tv --media-id 72844 --seasons all

# Request specific seasons
seerr-cli request create --media-type tv --media-id 72844 --seasons 1,2

# Request 4K version
seerr-cli request create --media-type movie --media-id 157336 --is4k

Manage existing requests:

seerr-cli request list                       # list all requests
seerr-cli request get 5                      # get specific request
seerr-cli request count                      # counts by status
seerr-cli request approve 5                  # approve
seerr-cli request decline 5                  # decline
seerr-cli request retry 5                    # retry failed request
seerr-cli request delete 5                   # delete

Media Management

seerr-cli media list                         # list all tracked media
seerr-cli media status 1 available           # update status
seerr-cli media watch-data 1                 # get watch data
seerr-cli media delete 1                     # remove from Seer
seerr-cli media delete-file 1                # delete file from Radarr/Sonarr

Issues

Report and track problems with media:

seerr-cli issue list                         # list all issues
seerr-cli issue create                       # create new issue
seerr-cli issue get 3                        # get issue details
seerr-cli issue count                        # issue counts
seerr-cli issue comment 3                    # add comment
seerr-cli issue update-status 3 resolved     # resolve issue
seerr-cli issue delete 3                     # delete issue

Watchlist

seerr-cli watchlist add --media-type movie --tmdb-id 157336
seerr-cli watchlist add --media-type tv --tmdb-id 72844
seerr-cli watchlist delete 1                 # remove by watchlist ID

Blocklist

Prevent media from appearing in discovery:

seerr-cli blocklist list                     # list blocked items
seerr-cli blocklist get 157336               # get by TMDB ID
seerr-cli blocklist add --tmdb-id 157336     # add to blocklist
seerr-cli blocklist delete 1                 # remove by ID

People

seerr-cli person get 525                     # person details
seerr-cli person combined-credits 525        # all movie + TV credits

Collections

seerr-cli collection get 2344               # collection details (e.g., a film series)

Users

seerr-cli users list                         # list all users
seerr-cli users get 1                        # user details
seerr-cli users create                       # create user
seerr-cli users update 1                     # update user
seerr-cli users delete 1                     # delete user
seerr-cli users requests 1                   # user's requests
seerr-cli users watchlist 1                  # user's watchlist
seerr-cli users watch-data 1                 # user's watch data
seerr-cli users quota 1                      # user's request quota
seerr-cli users import-from-plex             # import Plex users
seerr-cli users import-from-jellyfin         # import Jellyfin users
seerr-cli users bulk-update                  # bulk permission update
seerr-cli users settings get 1               # get user settings
seerr-cli users password reset 1             # reset password

Services (Radarr / Sonarr)

seerr-cli service radarr-list                # list Radarr servers
seerr-cli service radarr-get 1               # profiles + root folders
seerr-cli service sonarr-list                # list Sonarr servers
seerr-cli service sonarr-get 1               # profiles + root folders
seerr-cli service sonarr-lookup 72844        # look up series in Sonarr

TMDB Metadata

seerr-cli tmdb genres-movie                  # movie genre IDs
seerr-cli tmdb genres-tv                     # TV genre IDs
seerr-cli tmdb languages                     # supported languages
seerr-cli tmdb regions                       # supported regions
seerr-cli tmdb network 213                   # network details (e.g., Netflix)
seerr-cli tmdb studio 7505                   # studio details
seerr-cli tmdb backdrops                     # trending backdrops

Other Lookups

seerr-cli other certifications-movie         # movie age ratings by country
seerr-cli other certifications-tv            # TV age ratings by country
seerr-cli other keyword 180547               # keyword details
seerr-cli other watchprovider-regions        # available streaming regions
seerr-cli other watchproviders-movies        # movie streaming providers
seerr-cli other watchproviders-tv            # TV streaming providers

Override Rules

Custom rules for request routing:

seerr-cli overriderule list                  # list rules
seerr-cli overriderule create                # create rule
seerr-cli overriderule update 1              # update rule
seerr-cli overriderule delete 1              # delete rule

System Status

seerr-cli status system                      # server version + status
seerr-cli status appdata                     # app data volume info

MCP Server

seerr-cli mcp serve starts a Model Context Protocol server that exposes the Seerr API as tools. This lets AI agents (including Claude Desktop) use seerr-cli without invoking the CLI directly.

stdio transport (Claude Desktop)

Claude Desktop spawns the process and communicates over stdin/stdout. No authentication or network configuration required.

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "seer": {
      "command": "/usr/local/bin/seerr-cli",
      "args": ["mcp", "serve"],
      "env": {
        "SEERR_SERVER": "https://your-seerr-instance.com",
        "SEERR_API_KEY": "your-api-key"
      }
    }
  }
}

HTTP transport

For MCP clients that connect over HTTP with Bearer token auth:

seerr-cli mcp serve --transport http --addr :8811 --auth-token mysecrettoken

Endpoint: http://localhost:8811/mcp — set Authorization: Bearer mysecrettoken in your client.

For clients that cannot send custom headers (e.g. claude.ai remote MCP), use --allow-api-key-query-param (or SEERR_MCP_ALLOW_API_KEY_QUERY_PARAM):

# Add --cors if connecting from a browser-based client (e.g. claude.ai)
seerr-cli mcp serve --transport http --addr :8811 --allow-api-key-query-param --cors
# Endpoint: http://localhost:8811/mcp?api_key=YOUR_SEERR_API_KEY

All flags are configurable via environment variables:

Flag	Environment variable	Default
`--transport`	`SEERR_MCP_TRANSPORT`	`stdio`
`--addr`	`SEERR_MCP_ADDR`	`:8811`
`--auth-token`	`SEERR_MCP_AUTH_TOKEN`	—
`--no-auth`	`SEERR_MCP_NO_AUTH`	`false`
`--allow-api-key-query-param`	`SEERR_MCP_ALLOW_API_KEY_QUERY_PARAM`	`false`
`--cors`	`SEERR_MCP_CORS`	`false`
`--tls-cert`	`SEERR_MCP_TLS_CERT`	—
`--tls-key`	`SEERR_MCP_TLS_KEY`	—

Pass --cors (or SEERR_MCP_CORS=true) to enable CORS headers for browser-based clients (e.g. claude.ai). Disabled by default.

The HTTP transport does not implement OAuth 2.0. Use stdio for Claude Desktop.

MCP tools available

Category	Tools
Search	`search_multi`, `search_discover_movies`, `search_discover_tv`, `search_trending`
Movies	`movies_get`, `movies_recommendations`, `movies_similar`, `movies_ratings`
TV	`tv_get`, `tv_season`, `tv_recommendations`, `tv_similar`, `tv_ratings`
Requests	`request_list`, `request_get`, `request_create`, `request_approve`, `request_decline`, `request_delete`, `request_count`
Media	`media_list`, `media_status_update`
Issues	`issue_list`, `issue_get`, `issue_create`, `issue_status_update`, `issue_count`
Users	`users_list`, `users_get`, `users_quota`
People & Collections	`person_get`, `person_credits`, `collection_get`
Services	`service_radarr_list`, `service_sonarr_list`
Settings	`settings_about`, `settings_jobs_list`, `settings_jobs_run`
Watchlist & Blocklist	`watchlist_add`, `watchlist_remove`, `blocklist_list`, `blocklist_add`, `blocklist_remove`
System	`status_system`

Common Workflows

Find and request a movie

seerr-cli search multi -q "Interstellar"     # find TMDB ID
seerr-cli movies get 157336                  # confirm details
seerr-cli request create --media-type movie --media-id 157336

Find and request a TV show

seerr-cli search multi -q "Breaking Bad"    # find TMDB ID
seerr-cli tv get 1396                        # confirm details
seerr-cli request create --media-type tv --media-id 1396 --seasons all

Check what genre IDs mean

seerr-cli tmdb genres-movie                  # e.g., 28=Action, 18=Drama
seerr-cli tmdb genres-tv

Seerr server manager

安装技能