Installation

Prerequisites

  • Docker and Docker Compose
  • ~5.5 CPU cores and ~3 GB RAM available (container ceilings; actual usage is typically lower)

No other dependencies are required — everything runs in containers.

Install 

git clone -b main https://github.com/JGtHb/MCPbox.git
cd MCPbox

The main branch contains stable releases. The develop branch has the latest changes and is used for contributions.

Configure

Copy the example environment file and generate the required secrets:

cp .env.example .env

# Generate secrets and append to .env
echo "MCPBOX_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env
echo "POSTGRES_PASSWORD=$(openssl rand -hex 16)" >> .env
echo "SANDBOX_API_KEY=$(openssl rand -hex 32)" >> .env
Variable Purpose
MCPBOX_ENCRYPTION_KEY Encrypts server secrets (AES-256-GCM). Must be 64 hex characters.
POSTGRES_PASSWORD PostgreSQL database password.
SANDBOX_API_KEY Authenticates backend-to-sandbox communication. Min 32 characters.

Each secret must be a unique value. MCPBox checks on startup and logs a warning if duplicates are detected.

See Environment Variables for the full list of optional settings.

Start 

docker compose up -d

Database migrations run automatically on first startup. You can check the backend logs to confirm:

docker compose logs backend | grep "migrations"

Open http://localhost:3000 in your browser to access the admin UI.

Next Steps