Skip to main content

Configuration Reference

Complete reference for all PlexMCP configuration options.

Environment Variables​

All configuration is done through environment variables. Create a .env file or set them in your deployment environment.

Required Variables​

These must be set for PlexMCP to start:

VariableDescriptionExample
DATABASE_URLPostgreSQL connection stringpostgresql://user:pass@host:5432/db
JWT_SECRETSecret for signing JWTs (32+ chars)openssl rand -hex 32
API_KEY_HMAC_SECRETSecret for API key generation (32+ chars)openssl rand -hex 32
TOTP_ENCRYPTION_KEYKey for 2FA encryption (64 hex chars)openssl rand -hex 32

Server Configuration​

VariableDescriptionDefault
BIND_ADDRESSAddress to bind the server0.0.0.0:8080
PUBLIC_URLPublic URL of the APIhttp://localhost:8080
BASE_DOMAINBase domain for multi-tenant routinglocalhost

Database​

VariableDescriptionDefault
DATABASE_URLPrimary database connectionRequired
DATABASE_DIRECT_URLDirect connection (bypasses pooler)None
DATABASE_MAX_CONNECTIONSMax pool connections20

Redis​

VariableDescriptionDefault
REDIS_URLRedis connection stringredis://localhost:6379

Authentication​

VariableDescriptionDefault
JWT_SECRETJWT signing secretRequired
JWT_EXPIRY_HOURSToken expiration24
API_KEY_HMAC_SECRETAPI key signing secretRequired
TOTP_ENCRYPTION_KEY2FA encryption keyRequired

Feature Flags​

VariableDescriptionDefault
PLEXMCP_SELF_HOSTEDEnable self-hosted modefalse
ENABLE_SIGNUPAllow new user registrationtrue
ENABLE_BILLINGEnable Stripe billingtrue
ENABLE_EMAIL_ROUTINGEnable email featuresfalse

MCP Settings​

VariableDescriptionDefault
MCP_REQUEST_TIMEOUT_MSRequest timeout30000
MCP_PARTIAL_TIMEOUT_MSPartial response timeout5000
MCP_MAX_CONNECTIONS_PER_ORGMax connections per org100
MCP_MAX_REQUEST_BODY_BYTESMax request body size10485760 (10MB)

Logging​

VariableDescriptionDefault
RUST_LOGLog level configurationinfo,plexmcp=debug

Optional: Supabase (OAuth)​

VariableDescription
SUPABASE_URLSupabase project URL
SUPABASE_ANON_KEYSupabase anon key
SUPABASE_SERVICE_ROLE_KEYSupabase service role key
SUPABASE_JWT_SECRETSupabase JWT secret

Optional: Email (Resend)​

VariableDescription
RESEND_API_KEYResend API key
EMAIL_FROMSender email address
RESEND_WEBHOOK_SECRETWebhook signing secret

Optional: Stripe (Billing)​

VariableDescription
STRIPE_SECRET_KEYStripe API key
STRIPE_WEBHOOK_SECRETStripe webhook secret
STRIPE_PRICE_*Price IDs for plans

Configuration Examples​

Minimal Self-Hosted​

# .env
DATABASE_URL=postgresql://plexmcp:password@localhost:5432/plexmcp
REDIS_URL=redis://localhost:6379

JWT_SECRET=your-32-char-secret-here-abcdefghijklmnop
API_KEY_HMAC_SECRET=your-32-char-secret-here-abcdefghijklmnop
TOTP_ENCRYPTION_KEY=a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

PLEXMCP_SELF_HOSTED=true
ENABLE_BILLING=false

With Email Support​

# .env (add to minimal config)
RESEND_API_KEY=re_your_api_key
EMAIL_FROM=PlexMCP <noreply@yourdomain.com>

With OAuth (Google/GitHub)​

# .env (add to minimal config)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...
SUPABASE_JWT_SECRET=your-jwt-secret

Production Configuration​

# .env
# Database (external)
DATABASE_URL=postgresql://plexmcp:secure_password@db.example.com:5432/plexmcp

# Redis (external)
REDIS_URL=redis://redis.example.com:6379

# Server
BIND_ADDRESS=0.0.0.0:8080
PUBLIC_URL=https://api.yourdomain.com
BASE_DOMAIN=yourdomain.com

# Secrets (rotate these periodically!)
JWT_SECRET=<generate with: openssl rand -hex 32>
JWT_EXPIRY_HOURS=24
API_KEY_HMAC_SECRET=<generate with: openssl rand -hex 32>
TOTP_ENCRYPTION_KEY=<generate with: openssl rand -hex 32>

# Self-hosted mode
PLEXMCP_SELF_HOSTED=true
ENABLE_BILLING=false
ENABLE_SIGNUP=true
ENABLE_EMAIL_ROUTING=false

# MCP settings
MCP_REQUEST_TIMEOUT_MS=30000
MCP_MAX_CONNECTIONS_PER_ORG=100

# Logging (reduce verbosity in production)
RUST_LOG=info

Secret Generation​

Generate secure secrets:

# Generate all secrets at once
echo "JWT_SECRET=$(openssl rand -hex 32)"
echo "API_KEY_HMAC_SECRET=$(openssl rand -hex 32)"
echo "TOTP_ENCRYPTION_KEY=$(openssl rand -hex 32)"

Or use the setup script:

./scripts/setup.sh

Validation​

The API validates configuration on startup:

  • JWT_SECRET must be at least 32 characters
  • API_KEY_HMAC_SECRET must be at least 32 characters
  • TOTP_ENCRYPTION_KEY must be exactly 64 hex characters
  • Insecure default keys (all zeros, all ones) are rejected

Next Steps​