​

Database Configuration for MCPHub

​

Overview

​

Why Use Database Configuration?

• ✅ Better Persistence - Configuration stored in a professional database with transaction support and data integrity
• ✅ High Availability - Leverage database replication and failover capabilities
• ✅ Enterprise Ready - Meets enterprise data management and compliance requirements
• ✅ Backup & Recovery - Use mature database backup tools and strategies

​

Environment Variables

​

Required for Database Mode

# Database connection URL (PostgreSQL)
# Simply setting DB_URL will automatically enable database mode
DB_URL=postgresql://user:password@localhost:5432/mcphub

# Or explicitly control with USE_DB (overrides auto-detection)
# USE_DB=true

​

Setup Instructions

​

1. Using Docker

​

Option A: Using External Database

docker run -d \
  -p 3000:3000 \
  -v ./mcp_settings.json:/app/mcp_settings.json \
  -e DB_URL="postgresql://user:password@your-db-host:5432/mcphub" \
  samanhappy/mcphub

​

Option B: Using PostgreSQL as a separate service

version: '3.8'

services:
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_DB: mcphub
      POSTGRES_USER: mcphub
      POSTGRES_PASSWORD: your_secure_password
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  mcphub:
    image: samanhappy/mcphub:latest
    environment:
      USE_DB: "true"
      DB_URL: "postgresql://mcphub:your_secure_password@postgres:5432/mcphub"
      PORT: 3000
    ports:
      - "3000:3000"
    depends_on:
      - postgres

volumes:
  pgdata:

docker-compose up -d

​

2. Manual Setup

​

Step 1: Setup PostgreSQL Database

# Install PostgreSQL (if not already installed)
sudo apt-get install postgresql postgresql-contrib

# Create database and user
sudo -u postgres psql <<EOF
CREATE DATABASE mcphub;
CREATE USER mcphub WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE mcphub TO mcphub;
EOF

​

Step 2: Install MCPHub

npm install -g @samanhappy/mcphub

​

Step 3: Set Environment Variables

# Simply set DB_URL to enable database mode (USE_DB is auto-detected)
DB_URL=postgresql://mcphub:your_password@localhost:5432/mcphub
PORT=3000

​

Step 4: Run Migration (Optional)

# Run migration script
npx tsx src/scripts/migrate-to-database.ts

​

Step 5: Start MCPHub

mcphub

​

Migration from File-Based to Database

​

Automatic Migration

1. MCPHub connects to the database
2. Checks if any users exist in the database
3. If no users found, automatically migrates from mcp_settings.json
4. Creates all tables and imports all data

​

Manual Migration

# Using npx
npx tsx src/scripts/migrate-to-database.ts

# Or using Node
node dist/scripts/migrate-to-database.js

• ✅ Create database tables if they don’t exist
• ✅ Import all users with hashed passwords
• ✅ Import all MCP server configurations
• ✅ Import all groups
• ✅ Import system configuration
• ✅ Import user-specific configurations
• ✅ Skip existing records (safe to run multiple times)

​

Configuration After Migration

• User management via /api/users
• Server management via /api/servers
• Group management via /api/groups
• System settings via /api/system/config

​

Database Schema

• users - User accounts and authentication
• servers - MCP server configurations
• groups - Server groups
• system_config - System-wide settings
• user_configs - User-specific settings
• vector_embeddings - Vector search data (for smart routing)

​

Backup and Restore

​

Backup

# PostgreSQL backup
pg_dump -U mcphub mcphub > mcphub_backup.sql

# Or using Docker
docker exec postgres pg_dump -U mcphub mcphub > mcphub_backup.sql

​

Restore

# PostgreSQL restore
psql -U mcphub mcphub < mcphub_backup.sql

# Or using Docker
docker exec -i postgres psql -U mcphub mcphub < mcphub_backup.sql

​

Switching Back to File-Based Config

1. Set USE_DB=false or remove DB_URL and USE_DB environment variables
2. Restart MCPHub
3. MCPHub will use mcp_settings.json again

​

Troubleshooting

​

Connection Refused

Error: connect ECONNREFUSED 127.0.0.1:5432

# Check PostgreSQL status
sudo systemctl status postgresql

# Or for Docker
docker ps | grep postgres

​

Authentication Failed

Error: password authentication failed for user "mcphub"

​

Migration Failed

❌ Migration failed: ...

1. Check that mcp_settings.json exists and is valid JSON
2. Verify database connection
3. Check logs for specific error messages
4. Ensure database user has CREATE TABLE permissions

​

Tables Already Exist

1. Whether a previous migration partially completed
2. Manual table creation conflicts
3. Run with synchronize: false in database config if needed

​

Environment Variables Reference

​

Security Considerations

1. Database Credentials: Store database credentials securely, use environment variables or secrets management
2. Network Access: Restrict database access to MCPHub instances only
3. Encryption: Use SSL/TLS for database connections in production:
   DB_URL=postgresql://user:password@host:5432/mcphub?sslmode=require
   
4. Backup: Regularly backup your database
5. Access Control: Use strong database passwords and limit user permissions

​

Performance

• Multiple concurrent users
• Frequent configuration changes
• Large number of servers/groups

• Single user setups
• Read-heavy workloads with infrequent changes
• Development/testing environments