Configure MCPJungle's database

MCPJungle supports SQLite for local development and PostgreSQL for production. Configure the connection with a DSN or individual environment variables.

MCPJungle requires a database to persist registered MCP servers, tool groups, users, and configuration. By default it creates a SQLite file in the current working directory, which is convenient for local testing. For anything beyond that, use PostgreSQL.

Default: SQLite

When no database configuration is provided, MCPJungle automatically creates a SQLite file named mcpjungle.db in the directory where the process is started:

mcpjungle start
# Creates ./mcpjungle.db in the current directory

SQLite requires no setup and works well for individuals running MCPJungle locally. It is not recommended for production or multi-user deployments.

PostgreSQL

MCPJungle supports PostgreSQL for production workloads. You can configure the connection using either a full DSN or individual environment variables.

Option 1: Connection DSN

Set the DATABASE_URL environment variable to a full Postgres connection string:

Direct binary

export DATABASE_URL=postgres://admin:secret@localhost:5432/mcpjungle_db
mcpjungle start

Docker

docker run -d \
  --name mcpjungle-server \
  -e DATABASE_URL=postgres://admin:secret@your-db-host:5432/mcpjungle_db \
  -p 8080:8080 \
  ghcr.io/mcpjungle/mcpjungle:latest

Option 2: Individual environment variables

If you prefer not to construct a full DSN, set the individual Postgres variables instead. POSTGRES_HOST is required; all other variables are optional and have sensible defaults.

# Required
export POSTGRES_HOST=localhost

# Optional (defaults shown)
export POSTGRES_PORT=5432
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=secret
export POSTGRES_DB=postgres

mcpjungle start

Each credential variable also accepts a _FILE variant, which reads the value from a file. This is useful for Docker secrets and similar secret-injection mechanisms:

Variable	File variant	Default
POSTGRES_USER	POSTGRES_USER_FILE	postgres
POSTGRES_PASSWORD	POSTGRES_PASSWORD_FILE	(empty)
POSTGRES_DB	POSTGRES_DB_FILE	postgres

Example using file-based secrets:

export POSTGRES_HOST=localhost
export POSTGRES_USER_FILE=/run/secrets/pg_user
export POSTGRES_PASSWORD_FILE=/run/secrets/pg_password
export POSTGRES_DB_FILE=/run/secrets/pg_db

mcpjungle start

If both a variable and its _FILE counterpart are set, the plain variable takes precedence.

Variable precedence

When MCPJungle starts, it resolves the database connection in this order:

1. DATABASE_URL — used as-is if set
2. POSTGRES_HOST (+ optional variables) — constructs a DSN if POSTGRES_HOST is set
3. SQLite fallback — creates mcpjungle.db in the current directory

Production recommendations

Deploy a separate managed Postgres cluster (for example, RDS, Cloud SQL, or Supabase) and supply its endpoint via DATABASE_URL. Running the database in a sidecar container is acceptable for development but not recommended for production.

The production Docker Compose file (docker-compose.prod.yaml) bundles a Postgres 17 container for convenience. For a real deployment, replace it with a managed database service and update the DATABASE_URL accordingly.