seerr-cli

A command-line interface for the Seer media request management API. Built with Go and Cobra.

Installation

Quick Install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/electather/seerr-cli/main/install.sh | sh

Installs the latest stable release to /usr/local/bin (uses sudo if needed, falls back to ~/.local/bin). Supports amd64 and arm64.

Manual

Download the archive for your platform from the Releases page, extract it, and move the binary to your PATH.

Build from Source

git clone https://github.com/electather/seerr-cli.git
cd seerr-cli
go build -o seerr-cli .

Docker

A container image is published to the GitHub Container Registry on every release:

docker pull ghcr.io/electather/seerr-cli:latest

The image defaults to running the MCP HTTP server on port 8811. Pass configuration via environment variables:

docker run -d \
  -p 8811:8811 \
  -e SEERR_SERVER=https://your-seerr-instance.com \
  -e SEERR_API_KEY=your-api-key \
  -e SEERR_MCP_AUTH_TOKEN=mysecrettoken \
  ghcr.io/electather/seerr-cli:latest

To run CLI commands instead, override the default arguments:

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

Configuration

Set your server URL and API key once:

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

Configuration is stored in ~/.seerr-cli.yaml. You can also use environment variables:

export SEERR_SERVER=https://your-seerr-instance.com
export SEERR_API_KEY=YOUR_KEY

Or pass them as flags on any command:

seerr-cli --server https://your-seerr-instance.com --api-key YOUR_KEY <command>

View your current configuration:

seerr-cli config show

Global Flags

All commands support these flags:

Flag	Short	Description
`--server`	`-s`	Seerr server URL
`--api-key`	`-k`	Seerr API key
`--verbose`	`-v`	Show request URLs and HTTP status codes
`--config`		Path to config file (default: `~/.seerr-cli.yaml`)

Commands

Search

Search across movies, TV shows, and people.

# Multi-search (movies, TV, people)
seerr-cli search multi -q "The Matrix"
seerr-cli search multi -q "Christopher Nolan" --page 2

# Search TMDB keywords
seerr-cli search keyword -q "sci-fi"

# Search production companies
seerr-cli search company -q "Warner Bros."

# Trending content
seerr-cli search trending
seerr-cli search trending --time-window week

# Discover movies by genre, studio, or sort order
seerr-cli search movies --genre 18
seerr-cli search movies --studio 1
seerr-cli search movies --sort-by primary_release_date.desc

# Discover TV shows by genre or network
seerr-cli search tv --genre 18
seerr-cli search tv --network 1

Movies

# Get movie details by TMDB ID
seerr-cli movies get <tmdb-id>

# Get movie ratings
seerr-cli movies ratings <tmdb-id>
seerr-cli movies ratings-combined <tmdb-id>

# Get movie recommendations
seerr-cli movies recommendations <tmdb-id>

TV Shows

# Get TV show details
seerr-cli tv get <tmdb-id>

# Get ratings and recommendations
seerr-cli tv ratings <tmdb-id>
seerr-cli tv recommendations <tmdb-id>

# Get similar shows
seerr-cli tv similar <tmdb-id>

# Get season details
seerr-cli tv season <tmdb-id> <season-number>

Requests

Manage media requests (the core of Seer).

# Create a new request
seerr-cli request create <media-type> <tmdb-id>

# List request counts
seerr-cli request count

# Approve or decline requests
seerr-cli request approve <request-id>
seerr-cli request decline <request-id>

# Delete a request
seerr-cli request delete <request-id>

Media

# List all media
seerr-cli media list

# Check media status
seerr-cli media status <media-id>

# Delete media or specific files
seerr-cli media delete <media-id>
seerr-cli media delete-file <media-id>

Issues

# Create an issue for a media item
seerr-cli issue create <media-id>

# Get issue count
seerr-cli issue count

# Add a comment
seerr-cli issue comment <issue-id>

# Delete an issue or comment
seerr-cli issue delete <issue-id>
seerr-cli issue delete-comment <comment-id>

Users

# Get user details
seerr-cli users get <user-id>

# Create a new user
seerr-cli users create

# Import users (e.g., from Plex)
seerr-cli users import

# Bulk update users
seerr-cli users bulk-update

# Delete a user
seerr-cli users delete <user-id>

Watchlist

# Add to watchlist
seerr-cli watchlist add <media-type> <tmdb-id>

# Remove from watchlist
seerr-cli watchlist delete <media-type> <tmdb-id>

Blocklist

# List blocklist entries
seerr-cli blocklist list

# Get a specific entry
seerr-cli blocklist get <id>

# Add to blocklist
seerr-cli blocklist add <tmdb-id>

# Remove from blocklist
seerr-cli blocklist delete <id>

Collections

# Get collection details
seerr-cli collection get <collection-id>

Services

Check connected Radarr and Sonarr instances.

seerr-cli service radarr
seerr-cli service sonarr

Person

# Get person details
seerr-cli person get <person-id>

# Get combined credits
seerr-cli person combined-credits <person-id>

TMDB Data

Access TMDB metadata directly.

# List genres
seerr-cli tmdb genres-movie
seerr-cli tmdb genres-tv

# List languages
seerr-cli tmdb languages

# Get network details
seerr-cli tmdb network <network-id>

# Get movie backdrops
seerr-cli tmdb backdrops <tmdb-id>

Override Rules

# List override rules
seerr-cli overriderule list

# Create, update, or delete rules
seerr-cli overriderule create
seerr-cli overriderule update <rule-id>
seerr-cli overriderule delete <rule-id>

Other

# Get certification lists
seerr-cli other certifications-movie
seerr-cli other certifications-tv

# Get keyword details
seerr-cli other keyword <keyword-id>

# Get watch provider regions
seerr-cli other watchprovider-regions

System Status

# Get system status
seerr-cli status system

# Get app data path
seerr-cli status appdata

MCP Server

seerr-cli includes a built-in Model Context Protocol server that exposes the Seerr API as tools for AI agents.

Claude Desktop (stdio)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "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"
      }
    }
  }
}

Restart Claude Desktop. The Seerr tools will appear automatically.

HTTP transport (other MCP clients)

For clients that support HTTP MCP with Bearer token authentication:

# Start with a Bearer token
seerr-cli mcp serve --transport http --addr :8811 --auth-token mysecrettoken

# With TLS
seerr-cli mcp serve --transport http --addr :8811 \
  --auth-token mysecrettoken \
  --tls-cert /path/to/cert.pem \
  --tls-key /path/to/key.pem

# Without authentication (insecure — local use only)
seerr-cli mcp serve --transport http --addr :8811 --no-auth

The MCP endpoint is always http://localhost:8811/mcp. Configure your client with Authorization: Bearer mysecrettoken.

Note: The HTTP transport does not implement OAuth 2.0 and is not compatible with clients that require OAuth. Use stdio for Claude Desktop.

API key via query parameter (opt-in)

For clients that cannot set custom headers, the Seerr API key can be passed via the api_key query parameter when --allow-api-key-query-param is enabled. The X-Api-Key header takes precedence when both are present; requests with neither are rejected.

# Enable query parameter API key transport
seerr-cli mcp serve --transport http --allow-api-key-query-param

# Add --cors for browser-based clients (e.g. claude.ai)
seerr-cli mcp serve --transport http --allow-api-key-query-param --cors

MCP endpoint: http://localhost:8811/mcp?api_key=YOUR_SEERR_API_KEY

Security note: Query parameters may appear in proxy logs and browser history. Always serve over HTTPS when using query parameter transport.

Migration from `--route-token` or `--multi-tenant`

Both flags and their path-based routing have been removed. The MCP endpoint is now always /mcp. Clients that previously relied on these mechanisms should migrate to:

Header transport — send the Seerr API key as X-Api-Key: <key> on each request.
Query parameter transport — enable --allow-api-key-query-param and append ?api_key=<key> to the /mcp URL.
Bearer token — use --auth-token for MCP server access control (separate from the Seerr API key).

Environment variables

All mcp serve flags can be set via environment variables, which is especially useful for Docker deployments:

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`	—

Docker (HTTP transport)

The published container image runs the MCP HTTP server by default. This is the recommended way to self-host the MCP server:

# With Bearer token auth
docker run -d \
  --name seerr-mcp \
  -p 8811:8811 \
  -e SEERR_SERVER=https://your-seerr-instance.com \
  -e SEERR_API_KEY=your-api-key \
  -e SEERR_MCP_AUTH_TOKEN=mysecrettoken \
  ghcr.io/electather/seerr-cli:latest

Configure your MCP client with:

URL: http://localhost:8811/mcp
Authorization: Bearer mysecrettoken

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

docker run -d \
  --name seerr-mcp \
  -p 8811:8811 \
  -e SEERR_SERVER=https://your-seerr-instance.com \
  -e SEERR_API_KEY=your-api-key \
  -e SEERR_MCP_ALLOW_API_KEY_QUERY_PARAM=true \
  -e SEERR_MCP_CORS=true \
  ghcr.io/electather/seerr-cli:latest

Configure your MCP client with:

URL: http://localhost:8811/mcp?api_key=your-api-key

To bind to a different port or address, pass --addr explicitly:

docker run -d \
  -p 9000:9000 \
  -e SEERR_SERVER=https://your-seerr-instance.com \
  -e SEERR_API_KEY=your-api-key \
  -e SEERR_MCP_AUTH_TOKEN=mysecrettoken \
  ghcr.io/electather/seerr-cli:latest \
  mcp serve --transport http --addr :9000

Claude web (claude.ai)

Claude.ai connects to remote MCP servers over HTTPS. Since the browser cannot send custom headers, use --allow-api-key-query-param and expose the server via an HTTPS reverse proxy.

1. Start the MCP server

seerr-cli mcp serve \
  --transport http \
  --addr :8811 \
  --allow-api-key-query-param \
  --cors

The MCP endpoint will be http://localhost:8811/mcp.

2. Expose via HTTPS with a reverse proxy

The server must be reachable at a public HTTPS URL. Two common options:

Caddy (automatic TLS via Let's Encrypt):

mcp.example.com {
    reverse_proxy localhost:8811
}

nginx (with an existing TLS certificate):

server {
    listen 443 ssl;
    server_name mcp.example.com;

    ssl_certificate     /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8811;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

3. Add to claude.ai

Go to claude.ai → Settings → Integrations.
Click Add integration.
Enter the MCP URL: https://mcp.example.com/mcp?api_key=YOUR_SEERR_API_KEY
Save. The Seerr tools will appear in new conversations.

Security note: The Seerr API key in the query string is the credential protecting this endpoint. Always serve over HTTPS and use a key with appropriate permissions.

Health check

The HTTP server exposes an unauthenticated GET /health endpoint that returns a JSON status payload — no token required, even when --auth-token is set.

curl http://localhost:8811/health
# {"status":"ok","version":"1.2.3"}

This is used by the HEALTHCHECK instruction in the published Docker image and by the healthcheck: block in docker-compose.yml. For a container on a non-default port, adjust the URL accordingly:

docker run -d \
  --name seerr-mcp \
  -p 8811:8811 \
  --health-cmd "wget -qO- http://localhost:8811/health || exit 1" \
  --health-interval 30s \
  --health-timeout 5s \
  --health-start-period 5s \
  --health-retries 3 \
  -e SEERR_SERVER=https://your-seerr-instance.com \
  -e SEERR_API_KEY=your-api-key \
  -e SEERR_MCP_AUTH_TOKEN=mysecrettoken \
  ghcr.io/electather/seerr-cli:latest

Available tools (52)

Category	Tools
Search & Discovery	`search_multi`, `search_discover_movies`, `search_discover_tv`, `search_trending`, `search_company`, `search_keyword`
Movies	`movies_get`, `movies_recommendations`, `movies_similar`, `movies_ratings`, `movies_ratings_combined`
TV Shows	`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`, `request_retry`
Media	`media_list`, `media_status_update`
Issues	`issue_list`, `issue_get`, `issue_create`, `issue_status_update`, `issue_count`
Auth	`auth_me`
Users	`users_list`, `users_get`, `users_quota`, `users_update`
People	`person_get`, `person_credits`
Collections	`collection_get`
Services	`service_radarr_list`, `service_sonarr_list`
Settings	`settings_about`, `settings_jobs_list`, `settings_jobs_run`, `settings_jobs_cancel`, `settings_jobs_schedule`
Watchlist	`watchlist_add`, `watchlist_remove`
Blocklist	`blocklist_list`, `blocklist_add`, `blocklist_remove`
System	`status_system`

Available resources (9)

URI	Description
`seerr://genres/movies`	TMDB movie genre ID to name map
`seerr://genres/tv`	TMDB TV genre ID to name map
`seerr://languages`	ISO language codes and English names supported by TMDB
`seerr://regions`	ISO region codes and English names supported by TMDB
`seerr://certifications/movies`	Content ratings by country for movies (G, PG, R, etc.)
`seerr://certifications/tv`	Content ratings by country for TV shows
`seerr://services/radarr`	Configured Radarr instances with quality profiles and root folders
`seerr://services/sonarr`	Configured Sonarr instances with quality profiles and root folders
`seerr://system/about`	Seerr version, commit hash, and update availability

Supported Platforms

OS	Architecture
Linux	amd64, arm64
macOS	amd64, arm64
Windows	amd64

License

See the LICENSE file for details.

AI Disclosure

This project is my first experiment with AI-assisted development. The entire codebase was written by AI (Claude) under human supervision — I directed the design, reviewed every change, and made decisions about what to build and how, but the code itself was generated by AI.

I'm sharing this openly as part of exploring what it looks like to build real software with AI as a collaborator rather than just a code completion tool.

Name		Name	Last commit message	Last commit date
Latest commit History 80 Commits
.agent/skills		.agent/skills
.agents/skills		.agents/skills
.github		.github
cmd		cmd
internal/seerrclient		internal/seerrclient
pkg/api		pkg/api
tests		tests
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
AGENT.md		AGENT.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
generate-api-lib.sh		generate-api-lib.sh
go.mod		go.mod
go.sum		go.sum
go.work		go.work
go.work.sum		go.work.sum
install.sh		install.sh
main.go		main.go
open-api.yaml		open-api.yaml
seerr-cli.schema.json		seerr-cli.schema.json
skills-lock.json		skills-lock.json

Folders and files

Latest commit

History

Repository files navigation

seerr-cli

Installation

Quick Install (Linux / macOS)

Manual

Build from Source

Docker

Configuration

Global Flags

Commands

Search

Movies

TV Shows

Requests

Media

Issues

Users

Watchlist

Blocklist

Collections

Services

Person

TMDB Data

Override Rules

Other

System Status

MCP Server

Claude Desktop (stdio)

HTTP transport (other MCP clients)

API key via query parameter (opt-in)

Migration from --route-token or --multi-tenant

Environment variables

Docker (HTTP transport)

Claude web (claude.ai)

1. Start the MCP server

2. Expose via HTTPS with a reverse proxy

3. Add to claude.ai

Health check

Available tools (52)

Available resources (9)

Supported Platforms

License

AI Disclosure

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 19

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Migration from `--route-token` or `--multi-tenant`

Packages