{"id":47282067,"url":"https://github.com/electather/seerr-cli","last_synced_at":"2026-04-02T18:01:09.063Z","repository":{"id":343983772,"uuid":"1179337875","full_name":"electather/seerr-cli","owner":"electather","description":"CLI and MCP server for the Seerr media request management API","archived":false,"fork":false,"pushed_at":"2026-03-29T11:51:38.000Z","size":15013,"stargazers_count":1,"open_issues_count":13,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T14:29:04.942Z","etag":null,"topics":["cli","cobra","go","jellyfin","mcp","media-server","plex","seerr"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/electather.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T23:43:02.000Z","updated_at":"2026-03-29T11:50:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/electather/seerr-cli","commit_stats":null,"previous_names":["electather/seer-cli","electather/seerr-cli"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/electather/seerr-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electather%2Fseerr-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electather%2Fseerr-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electather%2Fseerr-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electather%2Fseerr-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/electather","download_url":"https://codeload.github.com/electather/seerr-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/electather%2Fseerr-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cobra","go","jellyfin","mcp","media-server","plex","seerr"],"created_at":"2026-03-16T01:58:08.256Z","updated_at":"2026-04-02T18:01:09.052Z","avatar_url":"https://github.com/electather.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# seerr-cli\n\nA command-line interface for the [Seer](https://github.com/seerr/app) media request management API. Built with Go and [Cobra](https://github.com/spf13/cobra).\n\n## Installation\n\n### Quick Install (Linux / macOS)\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/electather/seerr-cli/main/install.sh | sh\n```\n\nInstalls the latest stable release to `/usr/local/bin` (uses `sudo` if needed, falls back to `~/.local/bin`). Supports `amd64` and `arm64`.\n\n### Manual\n\nDownload the archive for your platform from the [Releases](https://github.com/electather/seerr-cli/releases) page, extract it, and move the binary to your `PATH`.\n\n### Build from Source\n\n```sh\ngit clone https://github.com/electather/seerr-cli.git\ncd seerr-cli\ngo build -o seerr-cli .\n```\n\n### Docker\n\nA container image is published to the GitHub Container Registry on every release:\n\n```sh\ndocker pull ghcr.io/electather/seerr-cli:latest\n```\n\nThe image defaults to running the MCP HTTP server on port `8811`. Pass configuration via environment variables:\n\n```sh\ndocker run -d \\\n  -p 8811:8811 \\\n  -e SEERR_SERVER=https://your-seerr-instance.com \\\n  -e SEERR_API_KEY=your-api-key \\\n  -e SEERR_MCP_AUTH_TOKEN=mysecrettoken \\\n  ghcr.io/electather/seerr-cli:latest\n```\n\nTo run CLI commands instead, override the default arguments:\n\n```sh\ndocker run --rm \\\n  -e SEERR_SERVER=https://your-seerr-instance.com \\\n  -e SEERR_API_KEY=your-api-key \\\n  ghcr.io/electather/seerr-cli:latest \\\n  status system\n```\n\n## Configuration\n\nSet your server URL and API key once:\n\n```sh\nseerr-cli config set --server https://your-seerr-instance.com --api-key YOUR_KEY\n```\n\nConfiguration is stored in `~/.seerr-cli.yaml`. You can also use environment variables:\n\n```sh\nexport SEERR_SERVER=https://your-seerr-instance.com\nexport SEERR_API_KEY=YOUR_KEY\n```\n\nOr pass them as flags on any command:\n\n```sh\nseerr-cli --server https://your-seerr-instance.com --api-key YOUR_KEY \u003ccommand\u003e\n```\n\nView your current configuration:\n\n```sh\nseerr-cli config show\n```\n\n## Global Flags\n\nAll commands support these flags:\n\n| Flag        | Short | Description                                        |\n| ----------- | ----- | -------------------------------------------------- |\n| `--server`  | `-s`  | Seerr server URL                                   |\n| `--api-key` | `-k`  | Seerr API key                                      |\n| `--verbose` | `-v`  | Show request URLs and HTTP status codes            |\n| `--config`  |       | Path to config file (default: `~/.seerr-cli.yaml`) |\n\n## Commands\n\n### Search\n\nSearch across movies, TV shows, and people.\n\n```sh\n# Multi-search (movies, TV, people)\nseerr-cli search multi -q \"The Matrix\"\nseerr-cli search multi -q \"Christopher Nolan\" --page 2\n\n# Search TMDB keywords\nseerr-cli search keyword -q \"sci-fi\"\n\n# Search production companies\nseerr-cli search company -q \"Warner Bros.\"\n\n# Trending content\nseerr-cli search trending\nseerr-cli search trending --time-window week\n\n# Discover movies by genre, studio, or sort order\nseerr-cli search movies --genre 18\nseerr-cli search movies --studio 1\nseerr-cli search movies --sort-by primary_release_date.desc\n\n# Discover TV shows by genre or network\nseerr-cli search tv --genre 18\nseerr-cli search tv --network 1\n```\n\n### Movies\n\n```sh\n# Get movie details by TMDB ID\nseerr-cli movies get \u003ctmdb-id\u003e\n\n# Get movie ratings\nseerr-cli movies ratings \u003ctmdb-id\u003e\nseerr-cli movies ratings-combined \u003ctmdb-id\u003e\n\n# Get movie recommendations\nseerr-cli movies recommendations \u003ctmdb-id\u003e\n```\n\n### TV Shows\n\n```sh\n# Get TV show details\nseerr-cli tv get \u003ctmdb-id\u003e\n\n# Get ratings and recommendations\nseerr-cli tv ratings \u003ctmdb-id\u003e\nseerr-cli tv recommendations \u003ctmdb-id\u003e\n\n# Get similar shows\nseerr-cli tv similar \u003ctmdb-id\u003e\n\n# Get season details\nseerr-cli tv season \u003ctmdb-id\u003e \u003cseason-number\u003e\n```\n\n### Requests\n\nManage media requests (the core of Seer).\n\n```sh\n# Create a new request\nseerr-cli request create \u003cmedia-type\u003e \u003ctmdb-id\u003e\n\n# List request counts\nseerr-cli request count\n\n# Approve or decline requests\nseerr-cli request approve \u003crequest-id\u003e\nseerr-cli request decline \u003crequest-id\u003e\n\n# Delete a request\nseerr-cli request delete \u003crequest-id\u003e\n```\n\n### Media\n\n```sh\n# List all media\nseerr-cli media list\n\n# Check media status\nseerr-cli media status \u003cmedia-id\u003e\n\n# Delete media or specific files\nseerr-cli media delete \u003cmedia-id\u003e\nseerr-cli media delete-file \u003cmedia-id\u003e\n```\n\n### Issues\n\n```sh\n# Create an issue for a media item\nseerr-cli issue create \u003cmedia-id\u003e\n\n# Get issue count\nseerr-cli issue count\n\n# Add a comment\nseerr-cli issue comment \u003cissue-id\u003e\n\n# Delete an issue or comment\nseerr-cli issue delete \u003cissue-id\u003e\nseerr-cli issue delete-comment \u003ccomment-id\u003e\n```\n\n### Users\n\n```sh\n# Get user details\nseerr-cli users get \u003cuser-id\u003e\n\n# Create a new user\nseerr-cli users create\n\n# Import users (e.g., from Plex)\nseerr-cli users import\n\n# Bulk update users\nseerr-cli users bulk-update\n\n# Delete a user\nseerr-cli users delete \u003cuser-id\u003e\n```\n\n### Watchlist\n\n```sh\n# Add to watchlist\nseerr-cli watchlist add \u003cmedia-type\u003e \u003ctmdb-id\u003e\n\n# Remove from watchlist\nseerr-cli watchlist delete \u003cmedia-type\u003e \u003ctmdb-id\u003e\n```\n\n### Blocklist\n\n```sh\n# List blocklist entries\nseerr-cli blocklist list\n\n# Get a specific entry\nseerr-cli blocklist get \u003cid\u003e\n\n# Add to blocklist\nseerr-cli blocklist add \u003ctmdb-id\u003e\n\n# Remove from blocklist\nseerr-cli blocklist delete \u003cid\u003e\n```\n\n### Collections\n\n```sh\n# Get collection details\nseerr-cli collection get \u003ccollection-id\u003e\n```\n\n### Services\n\nCheck connected Radarr and Sonarr instances.\n\n```sh\nseerr-cli service radarr\nseerr-cli service sonarr\n```\n\n### Person\n\n```sh\n# Get person details\nseerr-cli person get \u003cperson-id\u003e\n\n# Get combined credits\nseerr-cli person combined-credits \u003cperson-id\u003e\n```\n\n### TMDB Data\n\nAccess TMDB metadata directly.\n\n```sh\n# List genres\nseerr-cli tmdb genres-movie\nseerr-cli tmdb genres-tv\n\n# List languages\nseerr-cli tmdb languages\n\n# Get network details\nseerr-cli tmdb network \u003cnetwork-id\u003e\n\n# Get movie backdrops\nseerr-cli tmdb backdrops \u003ctmdb-id\u003e\n```\n\n### Override Rules\n\n```sh\n# List override rules\nseerr-cli overriderule list\n\n# Create, update, or delete rules\nseerr-cli overriderule create\nseerr-cli overriderule update \u003crule-id\u003e\nseerr-cli overriderule delete \u003crule-id\u003e\n```\n\n### Other\n\n```sh\n# Get certification lists\nseerr-cli other certifications-movie\nseerr-cli other certifications-tv\n\n# Get keyword details\nseerr-cli other keyword \u003ckeyword-id\u003e\n\n# Get watch provider regions\nseerr-cli other watchprovider-regions\n```\n\n### System Status\n\n```sh\n# Get system status\nseerr-cli status system\n\n# Get app data path\nseerr-cli status appdata\n```\n\n## MCP Server\n\n`seerr-cli` includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the Seerr API as tools for AI agents.\n\n### Claude Desktop (stdio)\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"seer\": {\n      \"command\": \"/usr/local/bin/seerr-cli\",\n      \"args\": [\"mcp\", \"serve\"],\n      \"env\": {\n        \"SEERR_SERVER\": \"https://your-seerr-instance.com\",\n        \"SEERR_API_KEY\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The Seerr tools will appear automatically.\n\n### HTTP transport (other MCP clients)\n\nFor clients that support HTTP MCP with Bearer token authentication:\n\n```sh\n# Start with a Bearer token\nseerr-cli mcp serve --transport http --addr :8811 --auth-token mysecrettoken\n\n# With TLS\nseerr-cli mcp serve --transport http --addr :8811 \\\n  --auth-token mysecrettoken \\\n  --tls-cert /path/to/cert.pem \\\n  --tls-key /path/to/key.pem\n\n# Without authentication (insecure — local use only)\nseerr-cli mcp serve --transport http --addr :8811 --no-auth\n```\n\nThe MCP endpoint is always `http://localhost:8811/mcp`. Configure your client with `Authorization: Bearer mysecrettoken`.\n\n\u003e **Note:** The HTTP transport does not implement OAuth 2.0 and is not compatible with clients that require OAuth. Use stdio for Claude Desktop.\n\n#### API key via query parameter (opt-in)\n\nFor 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.\n\n```sh\n# Enable query parameter API key transport\nseerr-cli mcp serve --transport http --allow-api-key-query-param\n\n# Add --cors for browser-based clients (e.g. claude.ai)\nseerr-cli mcp serve --transport http --allow-api-key-query-param --cors\n```\n\nMCP endpoint: `http://localhost:8811/mcp?api_key=YOUR_SEERR_API_KEY`\n\n\u003e **Security note:** Query parameters may appear in proxy logs and browser history. Always serve over HTTPS when using query parameter transport.\n\n#### Migration from `--route-token` or `--multi-tenant`\n\nBoth 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:\n\n- **Header transport** — send the Seerr API key as `X-Api-Key: \u003ckey\u003e` on each request.\n- **Query parameter transport** — enable `--allow-api-key-query-param` and append `?api_key=\u003ckey\u003e` to the `/mcp` URL.\n- **Bearer token** — use `--auth-token` for MCP server access control (separate from the Seerr API key).\n\n#### Environment variables\n\nAll `mcp serve` flags can be set via environment variables, which is especially useful for Docker deployments:\n\n| Flag                          | Environment variable                  | Default |\n| ----------------------------- | ------------------------------------- | ------- |\n| `--transport`                 | `SEERR_MCP_TRANSPORT`                 | `stdio` |\n| `--addr`                      | `SEERR_MCP_ADDR`                      | `:8811` |\n| `--auth-token`                | `SEERR_MCP_AUTH_TOKEN`                | —       |\n| `--no-auth`                   | `SEERR_MCP_NO_AUTH`                   | `false` |\n| `--allow-api-key-query-param` | `SEERR_MCP_ALLOW_API_KEY_QUERY_PARAM` | `false` |\n| `--cors`                      | `SEERR_MCP_CORS`                      | `false` |\n| `--tls-cert`                  | `SEERR_MCP_TLS_CERT`                  | —       |\n| `--tls-key`                   | `SEERR_MCP_TLS_KEY`                   | —       |\n\n### Docker (HTTP transport)\n\nThe published container image runs the MCP HTTP server by default. This is the recommended way to self-host the MCP server:\n\n```sh\n# With Bearer token auth\ndocker run -d \\\n  --name seerr-mcp \\\n  -p 8811:8811 \\\n  -e SEERR_SERVER=https://your-seerr-instance.com \\\n  -e SEERR_API_KEY=your-api-key \\\n  -e SEERR_MCP_AUTH_TOKEN=mysecrettoken \\\n  ghcr.io/electather/seerr-cli:latest\n```\n\nConfigure your MCP client with:\n\n- **URL:** `http://localhost:8811/mcp`\n- **Authorization:** `Bearer mysecrettoken`\n\nFor clients that cannot send custom headers (e.g. claude.ai remote MCP), use query parameter transport instead:\n\n```sh\ndocker run -d \\\n  --name seerr-mcp \\\n  -p 8811:8811 \\\n  -e SEERR_SERVER=https://your-seerr-instance.com \\\n  -e SEERR_API_KEY=your-api-key \\\n  -e SEERR_MCP_ALLOW_API_KEY_QUERY_PARAM=true \\\n  -e SEERR_MCP_CORS=true \\\n  ghcr.io/electather/seerr-cli:latest\n```\n\nConfigure your MCP client with:\n\n- **URL:** `http://localhost:8811/mcp?api_key=your-api-key`\n\nTo bind to a different port or address, pass `--addr` explicitly:\n\n```sh\ndocker run -d \\\n  -p 9000:9000 \\\n  -e SEERR_SERVER=https://your-seerr-instance.com \\\n  -e SEERR_API_KEY=your-api-key \\\n  -e SEERR_MCP_AUTH_TOKEN=mysecrettoken \\\n  ghcr.io/electather/seerr-cli:latest \\\n  mcp serve --transport http --addr :9000\n```\n\n### Claude web (claude.ai)\n\nClaude.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.\n\n#### 1. Start the MCP server\n\n```sh\nseerr-cli mcp serve \\\n  --transport http \\\n  --addr :8811 \\\n  --allow-api-key-query-param \\\n  --cors\n```\n\nThe MCP endpoint will be `http://localhost:8811/mcp`.\n\n#### 2. Expose via HTTPS with a reverse proxy\n\nThe server must be reachable at a public HTTPS URL. Two common options:\n\n**Caddy** (automatic TLS via Let's Encrypt):\n\n```\nmcp.example.com {\n    reverse_proxy localhost:8811\n}\n```\n\n**nginx** (with an existing TLS certificate):\n\n```nginx\nserver {\n    listen 443 ssl;\n    server_name mcp.example.com;\n\n    ssl_certificate     /etc/letsencrypt/live/mcp.example.com/fullchain.pem;\n    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;\n\n    location / {\n        proxy_pass http://localhost:8811;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n    }\n}\n```\n\n#### 3. Add to claude.ai\n\n1. Go to **claude.ai → Settings → Integrations**.\n2. Click **Add integration**.\n3. Enter the MCP URL: `https://mcp.example.com/mcp?api_key=YOUR_SEERR_API_KEY`\n4. Save. The Seerr tools will appear in new conversations.\n\n\u003e **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.\n\n#### Health check\n\nThe HTTP server exposes an unauthenticated `GET /health` endpoint that returns a JSON status payload — no token required, even when `--auth-token` is set.\n\n```sh\ncurl http://localhost:8811/health\n# {\"status\":\"ok\",\"version\":\"1.2.3\"}\n```\n\nThis 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:\n\n```sh\ndocker run -d \\\n  --name seerr-mcp \\\n  -p 8811:8811 \\\n  --health-cmd \"wget -qO- http://localhost:8811/health || exit 1\" \\\n  --health-interval 30s \\\n  --health-timeout 5s \\\n  --health-start-period 5s \\\n  --health-retries 3 \\\n  -e SEERR_SERVER=https://your-seerr-instance.com \\\n  -e SEERR_API_KEY=your-api-key \\\n  -e SEERR_MCP_AUTH_TOKEN=mysecrettoken \\\n  ghcr.io/electather/seerr-cli:latest\n```\n\n### Available tools (52)\n\n| Category           | Tools                                                                                                                                |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |\n| Search \u0026 Discovery | `search_multi`, `search_discover_movies`, `search_discover_tv`, `search_trending`, `search_company`, `search_keyword`                |\n| Movies             | `movies_get`, `movies_recommendations`, `movies_similar`, `movies_ratings`, `movies_ratings_combined`                                |\n| TV Shows           | `tv_get`, `tv_season`, `tv_recommendations`, `tv_similar`, `tv_ratings`                                                              |\n| Requests           | `request_list`, `request_get`, `request_create`, `request_approve`, `request_decline`, `request_delete`, `request_count`, `request_retry` |\n| Media              | `media_list`, `media_status_update`                                                                                                  |\n| Issues             | `issue_list`, `issue_get`, `issue_create`, `issue_status_update`, `issue_count`                                                      |\n| Auth               | `auth_me`                                                                                                                            |\n| Users              | `users_list`, `users_get`, `users_quota`, `users_update`                                                                             |\n| People             | `person_get`, `person_credits`                                                                                                       |\n| Collections        | `collection_get`                                                                                                                     |\n| Services           | `service_radarr_list`, `service_sonarr_list`                                                                                         |\n| Settings           | `settings_about`, `settings_jobs_list`, `settings_jobs_run`, `settings_jobs_cancel`, `settings_jobs_schedule`                        |\n| Watchlist          | `watchlist_add`, `watchlist_remove`                                                                                                  |\n| Blocklist          | `blocklist_list`, `blocklist_add`, `blocklist_remove`                                                                                |\n| System             | `status_system`                                                                                                                      |\n\n### Available resources (9)\n\n| URI                          | Description                                                    |\n| ---------------------------- | -------------------------------------------------------------- |\n| `seerr://genres/movies`      | TMDB movie genre ID to name map                                |\n| `seerr://genres/tv`          | TMDB TV genre ID to name map                                   |\n| `seerr://languages`          | ISO language codes and English names supported by TMDB         |\n| `seerr://regions`            | ISO region codes and English names supported by TMDB           |\n| `seerr://certifications/movies` | Content ratings by country for movies (G, PG, R, etc.)      |\n| `seerr://certifications/tv`  | Content ratings by country for TV shows                        |\n| `seerr://services/radarr`    | Configured Radarr instances with quality profiles and root folders |\n| `seerr://services/sonarr`    | Configured Sonarr instances with quality profiles and root folders |\n| `seerr://system/about`       | Seerr version, commit hash, and update availability            |\n\n## Supported Platforms\n\n| OS      | Architecture |\n| ------- | ------------ |\n| Linux   | amd64, arm64 |\n| macOS   | amd64, arm64 |\n| Windows | amd64        |\n\n## License\n\nSee the [LICENSE](LICENSE) file for details.\n\n## AI Disclosure\n\nThis 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.\n\nI'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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectather%2Fseerr-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felectather%2Fseerr-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felectather%2Fseerr-cli/lists"}