Configure mcpjungle's database

Mcpjungle requires a database to persist registered servers, tool groups, users, and related configuration. Use the database choice as a deployment signal:

SQLite for local evaluation and single-user experimentation.
PostgreSQL for anything shared, durable, or production-facing.

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. If you do not provide PostgreSQL settings or a custom SQLite path, Mcpjungle uses ./mcpjungle.db. You can optionally set a custom path for the SQLite file using either a command-line flag or an environment variable:

mcpjungle start --sqlite-db-path /path/to/my_custom_mcpjungle.db

# or
export SQLITE_DB_PATH=/var/lib/mcpjungle/.mcpjungle.db
mcpjungle start

PostgreSQL

Mcpjungle supports PostgreSQL for serious deployments. You can configure it with 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
Docker

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

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:

DATABASE_URL — used as-is if set
POSTGRES_HOST (+ optional variables) — constructs a DSN if POSTGRES_HOST is set
--sqlite-db-path — uses the configured SQLite file path from the CLI flag
SQLITE_DB_PATH — uses the configured SQLite file path from the environment variable
SQLite default — creates file mcpjungle.db in the current directory

Production recommendations

Deploy a separate Postgres cluster 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.

Get Started

Servers and Tools

Integrations

Deploy and Operate

Access and Governance

Limitations

Developers

Configure mcpjungle's database

Default: SQLite

PostgreSQL

Option 1: Connection DSN

Option 2: Individual environment variables

Variable precedence

Production recommendations

​Default: SQLite

​PostgreSQL

​Option 1: Connection DSN

​Option 2: Individual environment variables

​Variable precedence

​Production recommendations

Default: SQLite

PostgreSQL

Option 1: Connection DSN

Option 2: Individual environment variables

Variable precedence

Production recommendations