Environment Variables
Complete reference for all Mediabox MCP environment variables and their configuration.
All Mediabox MCP configuration is managed through a single .env file at the root of your project. This page documents every available variable.
Deployment
| Variable | Required | Default | Description |
|---|
DEPLOYMENT_MODE | Yes | local | Deployment mode: local or vps. |
TZ | No | UTC | Timezone for all services (e.g., America/New_York, Europe/London). |
Domain & SSL
These variables are required depending on the deployment mode selected during setup.
| Variable | Required | Default | Description |
|---|
BASE_DOMAIN | Conditional | — | Domain for services (e.g., media.example.com). Required for vps mode and Cloudflare Tunnel. |
LETSENCRYPT_EMAIL | Conditional | — | Email for Let’s Encrypt SSL certificates. Required for vps mode. |
CLOUDFLARE_TUNNEL_TOKEN | Conditional | — | Cloudflare Tunnel token from the Zero Trust dashboard. Required when using Cloudflare Tunnel. |
Service API Keys
| Variable | Required | Default | Description |
|---|
JELLYFIN_API_KEY | Yes | Extracted on first boot | API key for Jellyfin. Auto-generated by Jellyfin during initial setup, then extracted by the wizard. |
SONARR_API_KEY | Yes | Extracted on first boot | API key for Sonarr. Auto-generated by Sonarr on first run, extracted from config/sonarr/config.xml. |
RADARR_API_KEY | Yes | Extracted on first boot | API key for Radarr. Auto-generated by Radarr on first run, extracted from config/radarr/config.xml. |
PROWLARR_API_KEY | Yes | Extracted on first boot | API key for Prowlarr. Used by the setup API and dashboard to verify indexer/app configuration. |
QBIT_PASSWORD | Yes | — | Password for the qBittorrent web UI (username is admin). Minimum 8 characters. Set by user during wizard. |
PyLoad
| Variable | Required | Default | Description |
|---|
PYLOAD_USER | No | pyload | Username for PyLoad web UI and API authentication. |
PYLOAD_PASSWORD | No | pyload | Password for PyLoad web UI and API authentication. |
PYLOAD_HOST_PORT | No | 8001 | Host port used to open PyLoad from the dashboard. The container still listens internally on 8000. |
Optional Services
| Variable | Required | Default | Description |
|---|
BAZARR_ENABLED | No | false | Enables Bazarr status integration when the optional Bazarr service is present. |
BAZARR_URL | No | http://bazarr:6767 | Internal Bazarr URL. Desktop sidecar maps this to http://localhost:6767. |
FLARESOLVERR_URL | No | http://flaresolverr:8191 | Internal FlareSolverr URL used for health checks and indexer proxy setup. |
MCP Server
| Variable | Required | Default | Description |
|---|
MCP_PUBLIC_URL | Yes | http://localhost:3000 | The publicly accessible URL of the MCP server. Set to your domain URL when deploying with VPS or Tunnel mode. |
INTERNAL_API_KEY | Yes | Auto-generated | Internal API key for service-to-service communication (e.g., Telegram bot to MCP server). |
IMAGE_TAG | No | Current release | GHCR image tag used by generated Docker Compose files. Pin this for production instead of relying on latest. |
BIND_HOST | No | 0.0.0.0 | Interface the MCP server binds to. The Desktop sidecar forces 127.0.0.1; Docker deployments normally keep the default. |
ALLOWED_ORIGINS | No | MCP_PUBLIC_URL | Comma-separated browser origins allowed to call protected MCP/API endpoints. The server also allows localhost and Tauri app origins for local desktop usage. |
Telegram Integration (Optional)
These variables are only required if you enable the Telegram bot during setup.
| Variable | Required | Default | Description |
|---|
TELEGRAM_BOT_TOKEN | Conditional | — | Bot token from @BotFather. Required to enable the Telegram bot. |
ALLOWED_TELEGRAM_USERS | No | — | Comma-separated list of Telegram user IDs allowed to interact with the bot. Leave empty to allow all users. |
LLM Provider (Optional)
These variables configure the LLM used by the Desktop App chat and the optional Telegram bot to interpret natural language commands and call MCP tools.
| Variable | Required | Default | Description |
|---|
LLM_PROVIDER | Conditional | — | LLM provider for the app chat or Telegram bot. Supported: openrouter, google. Required when either chat surface is enabled. |
LLM_MODEL | No | Provider default | Optional model override. Examples: openai/gpt-4o, anthropic/claude-sonnet-4, gemini-2.0-flash. |
OPENROUTER_API_KEY | Conditional | — | API key for OpenRouter. Required when LLM_PROVIDER=openrouter. |
GOOGLE_AI_API_KEY | Conditional | — | API key for Google AI (Gemini). Required when LLM_PROVIDER=google. |
Example .env File
# Deployment
DEPLOYMENT_MODE=local
TZ=America/New_York
# Domain (uncomment for VPS mode)
# BASE_DOMAIN=media.example.com
# LETSENCRYPT_EMAIL=admin@example.com
# Service API Keys (extracted after first boot)
JELLYFIN_API_KEY=
SONARR_API_KEY=
RADARR_API_KEY=
PROWLARR_API_KEY=
QBIT_PASSWORD=your-secure-password
# PyLoad
PYLOAD_USER=pyload
PYLOAD_PASSWORD=pyload
PYLOAD_HOST_PORT=8001
# Optional services
BAZARR_ENABLED=false
# BAZARR_URL=http://bazarr:6767
# FLARESOLVERR_URL=http://flaresolverr:8191
# MCP Server
MCP_PUBLIC_URL=http://localhost:3000
INTERNAL_API_KEY=
IMAGE_TAG=2.2.0-beta.0
# BIND_HOST=0.0.0.0
ALLOWED_ORIGINS=http://localhost:3000
# Telegram (optional)
# TELEGRAM_BOT_TOKEN=123456:ABC-DEF
# LLM_PROVIDER=openrouter
# LLM_MODEL=openai/gpt-4o
# OPENROUTER_API_KEY=sk-or-...
# ALLOWED_TELEGRAM_USERS=12345678,87654321
Notes
- API keys for Jellyfin, Sonarr, Radarr, and Prowlarr are auto-generated by each service on first boot. The setup wizard extracts them automatically. For manual setup, extract them from the config XML files.
INTERNAL_API_KEY is auto-generated as a 32-character hex string by the wizard. For manual setup, generate it with: openssl rand -hex 32ALLOWED_ORIGINS should include the browser origins that need to call protected endpoints. The generated Compose file defaults it to MCP_PUBLIC_URL.IMAGE_TAG should match a published GHCR tag such as 2.2.0-beta.0, 2.2, latest, or sha-<commit>.- After changing any variable, recreate the affected containers:
docker compose up -d --force-recreate <service>