Navigation
On this page

Manual Setup

Step-by-step guide to setting up Mediabox MCP manually without the interactive wizard.

If you prefer full control over the setup process, you can set up Mediabox MCP manually using Docker Compose and environment variables.

1. Clone the Repository

git clone https://github.com/JuanCMPDev/mediabox-mcp.git
cd mediabox-mcp

2. Create Your Environment File

Copy the example environment file:

cp .env.example .env

3. Edit the Environment Variables

Open .env in your editor and fill in the required values:

# Deployment mode: local or vps
DEPLOYMENT_MODE=local

# Timezone
TZ=America/New_York

# Domain (only for VPS mode)
# BASE_DOMAIN=media.example.com

# Service API keys (leave empty for now — extracted after first boot)
JELLYFIN_API_KEY=
SONARR_API_KEY=
RADARR_API_KEY=

# qBittorrent password (min 8 characters)
QBIT_PASSWORD=your-secure-password

# PyLoad credentials
PYLOAD_USER=pyload
PYLOAD_PASSWORD=pyload

# MCP server
MCP_PUBLIC_URL=http://localhost:3000
MCP_AUTH_SECRET=your-random-hex-string-32-chars
INTERNAL_API_KEY=your-random-hex-string-32-chars

API keys for Jellyfin, Sonarr, and Radarr are auto-generated by each service on first boot. You will extract them in step 5.

For a complete list of variables, see Environment Variables.

4. Start the Stack

docker compose up -d

This pulls all required Docker images and starts the services. The first run may take several minutes.

Verify that all containers are running:

docker compose ps

5. Extract API Keys

Each service generates its own API key on first boot. Extract them from the config files:

# Sonarr API key
grep -oP '<ApiKey>\K[^<]+' config/sonarr/config.xml

# Radarr API key
grep -oP '<ApiKey>\K[^<]+' config/radarr/config.xml

Alternatively, find the API keys in each service’s web UI under Settings > General.

Update your .env file with the extracted keys:

JELLYFIN_API_KEY=extracted-key-here
SONARR_API_KEY=extracted-key-here
RADARR_API_KEY=extracted-key-here

Then recreate the MCP server container so it picks up the new environment:

docker compose up -d --force-recreate mcp-server

6. Configure Jellyfin

  1. Open Jellyfin at http://localhost:8096
  2. Complete the initial setup wizard (create admin user, set language)
  3. Create media libraries pointing to: /data/movies, /data/tv, /data/anime, /data/music
  4. Go to Dashboard > API Keys and create an API key — update your .env with this key

7. Configure Sonarr

  1. Open Sonarr at http://localhost:8989
  2. Go to Settings > Download Clients and add qBittorrent:
    • Host: qbittorrent
    • Port: 8085
    • Username: admin
    • Password: the QBIT_PASSWORD from your .env
  3. Go to Settings > Media Management and add root folders:
    • /data/tv for TV series
    • /data/anime for anime (if using separate library)

8. Configure Radarr

  1. Open Radarr at http://localhost:7878
  2. Go to Settings > Download Clients and add qBittorrent (same settings as Sonarr)
  3. Go to Settings > Media Management and add root folder:
    • /data/movies

9. Configure Prowlarr

  1. Open Prowlarr at http://localhost:9696
  2. Set up authentication under Settings > General
  3. Under Settings > Apps, add Sonarr and Radarr:
    • Sonarr: Prowlarr URL http://prowlarr:9696, Base URL http://sonarr:8989, API key from Sonarr’s config
    • Radarr: Prowlarr URL http://prowlarr:9696, Base URL http://radarr:7878, API key from Radarr’s config
  4. Add indexers — Navigate to Indexers > Add Indexer and add your preferred torrent trackers
  5. Configure FlareSolverr (if using indexers with Cloudflare protection):
    • Go to Settings > Indexer Proxies > add FlareSolverr with URL http://flaresolverr:8191/
    • Create a tag called flaresolverr under Indexers > Tags
    • Assign the tag to both the FlareSolverr proxy and the indexers that need it

10. Connect Your AI Client

Add the MCP server to your AI client configuration:

{
  "mcpServers": {
    "mediabox": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

If using VPS mode with a domain, replace with your MCP_PUBLIC_URL. OAuth2 authentication is handled automatically.

Next Steps