Installation Guide

Prerequisites

Before installing MCPHub, ensure you have the following prerequisites:

Node.js 18+ (for local development)
Docker (recommended for production)
pnpm (for local development)

Optional for Smart Routing:

PostgreSQL with pgvector extension
LLM Provider (OpenAI or compatible) API Key

Installation Methods

Docker (Recommended)
npm Package
Local Development
Kubernetes

Docker Installation

Docker is the recommended way to deploy MCPHub in production.

1. Basic Installation

# Pull the latest image
docker pull samanhappy/mcphub:latest

# Run with default settings
docker run -d \
  --name mcphub \
  -p 3000:3000 \
  samanhappy/mcphub:latest

2. With Custom Configuration

# Create your configuration file
cat > mcp_settings.json << 'EOF'
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    }
  }
}
EOF

# Run with mounted config
docker run -d \
  --name mcphub \
  -p 3000:3000 \
  -v $(pwd)/mcp_settings.json:/app/mcp_settings.json \
  samanhappy/mcphub:latest

3. With Environment Variables

docker run -d \
  --name mcphub \
  -p 3000:3000 \
  -e PORT=3000 \
  -e BASE_PATH="" \
  samanhappy/mcphub:latest

4. Docker Compose

Create a docker-compose.yml file:

version: '3.8'
services:
  mcphub:
    image: samanhappy/mcphub:latest
    ports:
      - "3000:3000"
    volumes:
      - ./mcp_settings.json:/app/mcp_settings.json
    environment:
      - PORT=3000
      - BASE_PATH=
      - INIT_TIMEOUT=300000
    restart: unless-stopped

  # Optional: PostgreSQL for Smart Routing
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_DB: mcphub
      POSTGRES_USER: mcphub
      POSTGRES_PASSWORD: mcphub_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  postgres_data:

Run with:

docker-compose up -d

npm Package Installation

Install MCPHub as a global npm package:

1. Global Installation

# Install globally
npm install -g @samanhappy/mcphub

# Or with yarn
yarn global add @samanhappy/mcphub

# Or with pnpm
pnpm add -g @samanhappy/mcphub

2. Running MCPHub

# Run with default settings
mcphub

# Run with custom port
PORT=8080 mcphub

Local Development Setup

For development, customization, or contribution:

1. Clone Repository

# Clone the repository
git clone https://github.com/samanhappy/mcphub.git
cd mcphub

2. Install Dependencies

# Install dependencies with pnpm (recommended)
pnpm install

# Or with npm
npm install

# Or with yarn
yarn install

3. Development Mode

# Start both backend and frontend in development mode
pnpm dev

# This will start:
# - Backend on http://localhost:3000
# - Frontend on http://localhost:5173
# - Frontend proxies API calls to backend

4. Build for Production

# Build both backend and frontend
pnpm build

# Start production server
pnpm start

5. Development Scripts

# Backend only (for API development)
pnpm backend:dev

# Frontend only (when backend is running separately)
pnpm frontend:dev

# Run tests
pnpm test

# Lint code
pnpm lint

# Format code
pnpm format

On Windows, you may need to run backend and frontend separately:

# Terminal 1: Backend
pnpm backend:dev

# Terminal 2: Frontend
pnpm frontend:dev

Kubernetes Deployment

Deploy MCPHub on Kubernetes with these manifests:

1. ConfigMap for Settings

apiVersion: v1
kind: ConfigMap
metadata:
  name: mcphub-config
data:
  mcp_settings.json: |
    {
      "mcpServers": {
        "fetch": {
          "command": "uvx",
          "args": ["mcp-server-fetch"]
        },
        "playwright": {
          "command": "npx",
          "args": ["@playwright/mcp@latest", "--headless"]
        }
      }
    }

2. Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcphub
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mcphub
  template:
    metadata:
      labels:
        app: mcphub
    spec:
      initContainers:
        - name: prepare-config
          image: busybox:1.28
          command:
            [
              "sh",
              "-c",
              "cp /config-ro/mcp_settings.json /etc/mcphub/mcp_settings.json",
            ]
          volumeMounts:
            - name: config
              mountPath: /config-ro
              readOnly: true
            - name: app-storage
              mountPath: /etc/mcphub
      containers:
        - name: mcphub
          image: samanhappy/mcphub:latest
          ports:
            - containerPort: 3000
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi
          env:
            - name: PORT
              value: "3000"
            - name: MCPHUB_SETTING_PATH
              value: /etc/mcphub/mcp_settings.json
          volumeMounts:
            - name: app-storage
              mountPath: /etc/mcphub
      volumes:
        - name: config
          configMap:
            name: mcphub-config
        - name: app-storage
          emptyDir: {}

3. Service

apiVersion: v1
kind: Service
metadata:
  name: mcphub-service
spec:
  selector:
    app: mcphub
  ports:
  - port: 80
    targetPort: 3000
  type: ClusterIP

4. Ingress (Optional)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mcphub-ingress
  annotations:
    nginx.ingress.kubernetes.io/proxy-buffering: "off"
spec:
  rules:
  - host: mcphub.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: mcphub-service
            port:
              number: 80

Deploy with:

kubectl apply -f mcphub-configmap.yaml
kubectl apply -f mcphub-deployment.yaml
kubectl apply -f mcphub-service.yaml
kubectl apply -f mcphub-ingress.yaml

Smart Routing Setup (Optional)

Smart Routing provides AI-powered tool discovery using vector semantic search.

Prerequisites

PostgreSQL with pgvector
LLM Provider (OpenAI or compatible) API Key

Database Setup

Docker PostgreSQL
Existing PostgreSQL
Cloud PostgreSQL

# Run PostgreSQL with pgvector
docker run -d \
  --name mcphub-postgres \
  -e POSTGRES_DB=mcphub \
  -e POSTGRES_USER=mcphub \
  -e POSTGRES_PASSWORD=your_password \
  -p 5432:5432 \
  pgvector/pgvector:pg17

If you have an existing PostgreSQL instance:

-- Connect to your PostgreSQL instance
-- Create database
CREATE DATABASE mcphub;

-- Connect to the mcphub database
\c mcphub;

-- Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

For cloud providers (AWS RDS, Google Cloud SQL, etc.):

Enable the pgvector extension in your cloud provider’s console
Create a database named mcphub
Note down the connection details

Verification

After installation, verify MCPHub is working:

Dashboard Access

Open your browser and navigate to:

http://localhost:3000

Log in with username admin. On first launch, if no ADMIN_PASSWORD environment variable is set, a random password is generated and printed to the server logs.

Troubleshooting

Docker Issues

Port already in use:

# Check what's using port 3000
lsof -i :3000

# Use a different port
docker run -p 8080:3000 samanhappy/mcphub

Container won’t start:

# Check container logs
docker logs mcphub

# Run interactively for debugging
docker run -it --rm samanhappy/mcphub /bin/bash

npm Installation Issues

Permission errors:

# Use npx instead of global install
npx @samanhappy/mcphub

# Or fix npm permissions
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Node version issues:

# Check Node version
node --version

# Install Node 18+ using nvm
nvm install 18
nvm use 18

Network Issues

Can’t access dashboard:

Check if MCPHub is running: ps aux | grep mcphub
Verify port binding: netstat -tlnp | grep 3000
Check firewall settings
Try accessing via 127.0.0.1:3000 instead of localhost:3000

AI clients can’t connect:

Ensure the endpoint URL is correct
Check if MCPHub is behind a proxy
Verify network policies in Kubernetes/Docker environments

Smart Routing Issues

Database connection failed:

# Test database connection
psql $DB_URL -c "SELECT 1;"

# Check if pgvector is installed
psql $DB_URL -c "CREATE EXTENSION IF NOT EXISTS vector;"

Embedding service errors:

Verify LLM provider API key is valid
Check internet connectivity
Monitor rate limits

Next Steps

Configuration

Configure your MCP servers and settings

Quick Start

Get up and running in 5 minutes

Server Management

Learn how to manage your MCP servers

API Reference

Explore the complete API documentation

Get Started

Core Features

Configuration

Development

Prerequisites

Installation Methods

Docker Installation

1. Basic Installation

2. With Custom Configuration

3. With Environment Variables

4. Docker Compose

npm Package Installation

1. Global Installation

2. Running MCPHub

Local Development Setup

1. Clone Repository

2. Install Dependencies

3. Development Mode

4. Build for Production

5. Development Scripts

Kubernetes Deployment

1. ConfigMap for Settings

2. Deployment

3. Service

4. Ingress (Optional)

Smart Routing Setup (Optional)

Prerequisites

Database Setup

Verification

Dashboard Access

Troubleshooting

Next Steps

Configuration

Quick Start

Server Management

API Reference

​Prerequisites

​Installation Methods

​Docker Installation

​1. Basic Installation

​2. With Custom Configuration

​3. With Environment Variables

​4. Docker Compose

​npm Package Installation

​1. Global Installation

​2. Running MCPHub

​Local Development Setup

​1. Clone Repository

​2. Install Dependencies

​3. Development Mode

​4. Build for Production

​5. Development Scripts

​Kubernetes Deployment

​1. ConfigMap for Settings

​2. Deployment

​3. Service

​4. Ingress (Optional)

​Smart Routing Setup (Optional)

​Prerequisites

​Database Setup

​Verification

​Dashboard Access

​Troubleshooting

​Next Steps

Configuration

Quick Start

Server Management

API Reference

Prerequisites

Installation Methods

Docker Installation

1. Basic Installation

2. With Custom Configuration

3. With Environment Variables

4. Docker Compose

npm Package Installation

1. Global Installation

2. Running MCPHub

Local Development Setup

1. Clone Repository

2. Install Dependencies

3. Development Mode

4. Build for Production

5. Development Scripts

Kubernetes Deployment

1. ConfigMap for Settings

2. Deployment

3. Service

4. Ingress (Optional)

Smart Routing Setup (Optional)

Prerequisites

Database Setup

Verification

Dashboard Access

Troubleshooting

Next Steps