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. |
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. |
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. |
MCP_AUTH_SECRET | Yes | Auto-generated | 32-character hex secret used for OAuth2 authentication. Auto-generated by the wizard. |
INTERNAL_API_KEY | Yes | Auto-generated | Internal API key for service-to-service communication (e.g., Telegram bot to MCP server). |
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 Telegram bot to interpret natural language commands and call MCP tools.
| Variable | Required | Default | Description |
|---|
LLM_PROVIDER | Conditional | — | LLM provider for the Telegram bot. Supported: openrouter, google. Required if Telegram bot is enabled. |
LLM_MODEL | No | openai/gpt-4o | Model identifier (only for OpenRouter). Examples: openai/gpt-4o, anthropic/claude-sonnet-4. |
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
# [email protected]
# Service API Keys (extracted after first boot)
JELLYFIN_API_KEY=
SONARR_API_KEY=
RADARR_API_KEY=
QBIT_PASSWORD=your-secure-password
# PyLoad
PYLOAD_USER=pyload
PYLOAD_PASSWORD=pyload
# MCP Server
MCP_PUBLIC_URL=http://localhost:3000
MCP_AUTH_SECRET=
INTERNAL_API_KEY=
# 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, and Radarr 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.
MCP_AUTH_SECRET and INTERNAL_API_KEY are auto-generated as 32-character hex strings by the wizard. For manual setup, generate them with: openssl rand -hex 32- After changing any variable, recreate the affected containers:
docker compose up -d --force-recreate <service>