mirrors/mcphub
1
0
Fork 0
mirror of https://github.com/samanhappy/mcphub.git synced 2025-12-24 02:39:19 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
017e405c41fda4f7328eca78157b41359697a31e
mcphub/docs/installation.mdx
Chengwei Guo a4e4791b60 fix the deployment on kubernetes (#417)
2025-11-03 14:16:12 +08:00

596 lines
12 KiB
Plaintext
Raw Blame History

---
title: 'Installation Guide'
description: 'Detailed installation instructions for all platforms'
---
## 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
- **OpenAI API Key** or compatible embedding service
## Installation Methods
<Tabs>
<Tab title="Docker (Recommended)">
### Docker Installation
Docker is the recommended way to deploy MCPHub in production.
#### 1. Basic Installation
```bash
# 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
```bash
# 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
```bash
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:
```yaml
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=""
- REQUEST_TIMEOUT=60000
restart: unless-stopped
# Optional: PostgreSQL for Smart Routing
postgres:
image: pgvector/pgvector:pg16
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:
```bash
docker-compose up -d
```
</Tab>
<Tab title="npm Package">
### npm Package Installation
Install MCPHub as a global npm package:
#### 1. Global Installation
```bash
# 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
```bash
# Run with default settings
mcphub
# Run with custom port
PORT=8080 mcphub
```
{/* #### 3. Local Installation
You can also install MCPHub locally in a project:
```bash
# Create a new directory
mkdir my-mcphub
cd my-mcphub
# Initialize package.json
npm init -y
# Install MCPHub locally
npm install @samanhappy/mcphub
# Create a start script
echo '#!/bin/bash\nnpx mcphub' > start.sh
chmod +x start.sh
# Run MCPHub
./start.sh
``` */}
</Tab>
<Tab title="Local Development">
### Local Development Setup
For development, customization, or contribution:
#### 1. Clone Repository
```bash
# Clone the repository
git clone https://github.com/samanhappy/mcphub.git
cd mcphub
```
#### 2. Install Dependencies
```bash
# Install dependencies with pnpm (recommended)
pnpm install
# Or with npm
npm install
# Or with yarn
yarn install
```
#### 3. Development Mode
```bash
# Start both backend and frontend in development mode
pnpm dev
# This will start:
# - Backend on http://localhost:3001
# - Frontend on http://localhost:5173
# - Frontend proxies API calls to backend
```
#### 4. Build for Production
```bash
# Build both backend and frontend
pnpm build
# Start production server
pnpm start
```
#### 5. Development Scripts
```bash
# 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
```
<Note>
On Windows, you may need to run backend and frontend separately:
```bash
# Terminal 1: Backend
pnpm backend:dev
# Terminal 2: Frontend
pnpm frontend:dev
```
</Note>
</Tab>
<Tab title="Kubernetes">
### Kubernetes Deployment
Deploy MCPHub on Kubernetes with these manifests:
#### 1. ConfigMap for Settings
```yaml
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
```yaml
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
```yaml
apiVersion: v1
kind: Service
metadata:
name: mcphub-service
spec:
selector:
app: mcphub
ports:
- port: 80
targetPort: 3000
type: ClusterIP
```
#### 4. Ingress (Optional)
```yaml
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:
```bash
kubectl apply -f mcphub-configmap.yaml
kubectl apply -f mcphub-deployment.yaml
kubectl apply -f mcphub-service.yaml
kubectl apply -f mcphub-ingress.yaml
```
</Tab>
</Tabs>
## Smart Routing Setup (Optional)
Smart Routing provides AI-powered tool discovery using vector semantic search.
### Prerequisites
1. **PostgreSQL with pgvector**
2. **OpenAI API Key** (or compatible embedding service)
### Database Setup
<Tabs>
<Tab title="Docker PostgreSQL">
```bash
# 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:pg16
```
</Tab>
<Tab title="Existing PostgreSQL">
If you have an existing PostgreSQL instance:
```sql
-- 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;
```
</Tab>
<Tab title="Cloud PostgreSQL">
For cloud providers (AWS RDS, Google Cloud SQL, etc.):
1. Enable the pgvector extension in your cloud provider's console
2. Create a database named `mcphub`
3. Note down the connection details
</Tab>
</Tabs>
{/* ### Environment Configuration
Set the following environment variables:
```bash
# Database connection
DATABASE_URL=postgresql://mcphub:your_password@localhost:5432/mcphub
# OpenAI API for embeddings
OPENAI_API_KEY=your_openai_api_key
# Optional: Custom embedding model
EMBEDDING_MODEL=text-embedding-3-small
# Optional: Enable smart routing
ENABLE_SMART_ROUTING=true
``` */}
## Verification
After installation, verify MCPHub is working:
{/* ### 1. Health Check
```bash
curl http://localhost:3000/api/health
```
Expected response:
```json
{
"status": "ok",
"version": "x.x.x",
"uptime": 123
}
``` */}
### Dashboard Access
Open your browser and navigate to:
```
http://localhost:3000
```
{/* ### 3. API Test
```bash
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}'
``` */}
## Troubleshooting
<AccordionGroup>
<Accordion title="Docker Issues">
**Port already in use:**
```bash
# Check what's using port 3000
lsof -i :3000
# Use a different port
docker run -p 8080:3000 samanhappy/mcphub
```
**Container won't start:**
```bash
# Check container logs
docker logs mcphub
# Run interactively for debugging
docker run -it --rm samanhappy/mcphub /bin/bash
```
</Accordion>
<Accordion title="npm Installation Issues">
**Permission errors:**
```bash
# 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:**
```bash
# Check Node version
node --version
# Install Node 18+ using nvm
nvm install 18
nvm use 18
```
</Accordion>
<Accordion title="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
</Accordion>
<Accordion title="Smart Routing Issues">
**Database connection failed:**
```bash
# Test database connection
psql $DATABASE_URL -c "SELECT 1;"
# Check if pgvector is installed
psql $DATABASE_URL -c "CREATE EXTENSION IF NOT EXISTS vector;"
```
**Embedding service errors:**
- Verify OpenAI API key is valid
- Check internet connectivity
- Monitor rate limits
</Accordion>
</AccordionGroup>
## Next Steps
<CardGroup cols={2}>
<Card title="Configuration" icon="cog" href="/configuration/mcp-settings">
Configure your MCP servers and settings
</Card>
<Card title="Quick Start" icon="rocket" href="/quickstart">
Get up and running in 5 minutes
</Card>
<Card title="Server Management" icon="server" href="/features/server-management">
Learn how to manage your MCP servers
</Card>
<Card title="API Reference" icon="code" href="/api-reference/introduction">
Explore the complete API documentation
</Card>
</CardGroup>
Reference in New Issue View Git Blame Copy Permalink