安装指南

先决条件

在安装 MCPHub 之前，请确保您具备以下先决条件：

Node.js 18+ (用于本地开发)
Docker (推荐用于生产环境)
pnpm (用于本地开发)

智能路由的可选要求：

PostgreSQL 带 pgvector 扩展
LLM 提供商（OpenAI 或兼容）API 密钥

安装方法

Docker (推荐)
npm 包
本地开发
Kubernetes

Docker 安装

Docker 是在生产环境中部署 MCPHub 的推荐方式。

1. 基础安装

# 拉取最新镜像
docker pull samanhappy/mcphub:latest

# 使用默认设置运行
docker run -d \
  --name mcphub \
  -p 3000:3000 \
  samanhappy/mcphub:latest

2. 使用自定义配置

# 创建您的配置文件
cat > mcp_settings.json << 'EOF'
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    }
  }
}
EOF

# 使用挂载的配置运行
docker run -d \
  --name mcphub \
  -p 3000:3000 \
  -v $(pwd)/mcp_settings.json:/app/mcp_settings.json \
  samanhappy/mcphub:latest

3. 使用环境变量

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

4. Docker Compose

创建 docker-compose.yml 文件：

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

  # 可选：用于智能路由的 PostgreSQL
  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:

运行命令：

docker-compose up -d

npm 包安装

将 MCPHub 安装为全局 npm 包：

1. 全局安装

# 全局安装
npm install -g @samanhappy/mcphub

# 或使用 yarn
yarn global add @samanhappy/mcphub

# 或使用 pnpm
pnpm add -g @samanhappy/mcphub

2. 运行 MCPHub

# 使用默认设置运行
mcphub

# 使用自定义端口运行
PORT=8080 mcphub

本地开发环境设置

用于开发、自定义或贡献：

1. 克隆仓库

# 克隆仓库
git clone https://github.com/samanhappy/mcphub.git
cd mcphub

2. 安装依赖

# 使用 pnpm 安装依赖（推荐）
pnpm install

# 或使用 npm
npm install

# 或使用 yarn
yarn install

3. 开发模式

# 在开发模式下同时启动后端和前端
pnpm dev

# 这将启动：
# - 后端在 http://localhost:3000
# - 前端在 http://localhost:5173
# - 前端代理 API 调用到后端

4. 生产构建

# 构建后端和前端
pnpm build

# 启动生产服务器
pnpm start

5. 开发脚本

# 仅后端（用于 API 开发）
pnpm backend:dev

# 仅前端（当后端单独运行时）
pnpm frontend:dev

# 运行测试
pnpm test

# 代码检查
pnpm lint

# 代码格式化
pnpm format

在 Windows 上，您可能需要分别运行后端和前端：

# 终端 1：后端
pnpm backend:dev

# 终端 2：前端
pnpm frontend:dev

Kubernetes 部署

使用这些清单在 Kubernetes 上部署 MCPHub：

1. 设置的 ConfigMap

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. 部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcphub
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mcphub
  template:
    metadata:
      labels:
        app: mcphub
    spec:
      containers:
      - name: mcphub
        image: samanhappy/mcphub:latest
        ports:
        - containerPort: 3000
        env:
        - name: PORT
          value: "3000"
        volumeMounts:
        - name: config
          mountPath: /app/mcp_settings.json
          subPath: mcp_settings.json
      volumes:
      - name: config
        configMap:
          name: mcphub-config

3. 服务

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

4. Ingress (可选)

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

部署命令：

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

智能路由设置 (可选)

智能路由使用向量语义搜索提供 AI 驱动的工具发现。

先决条件

PostgreSQL 带 pgvector 扩展
LLM 提供商（OpenAI 或兼容）API 密钥

数据库设置

Docker PostgreSQL
现有 PostgreSQL
云 PostgreSQL

# 运行带 pgvector 的 PostgreSQL
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

如果您有现有的 PostgreSQL 实例：

-- 连接到您的 PostgreSQL 实例
-- 创建数据库
CREATE DATABASE mcphub;

-- 连接到 mcphub 数据库
\c mcphub;

-- 启用 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;

对于云提供商（AWS RDS、Google Cloud SQL 等）：

在您的云提供商控制台中启用 pgvector 扩展
创建名为 mcphub 的数据库
记下连接详细信息

验证

安装后，验证 MCPHub 是否正常工作：

控制台访问

打开浏览器并导航到：

http://localhost:3000

故障排除

Docker 问题

端口已被使用：

# 检查是什么在使用端口 3000
lsof -i :3000

# 使用不同的端口
docker run -p 8080:3000 samanhappy/mcphub

容器无法启动：

# 检查容器日志
docker logs mcphub

# 交互式运行以进行调试
docker run -it --rm samanhappy/mcphub /bin/bash

npm 安装问题

权限错误：

# 使用 npx 而不是全局安装
npx @samanhappy/mcphub

# 或修复 npm 权限
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Node 版本问题：

# 检查 Node 版本
node --version

# 使用 nvm 安装 Node 18+
nvm install 18
nvm use 18

网络问题

无法访问控制台：

检查 MCPHub 是否在运行：ps aux | grep mcphub
验证端口绑定：netstat -tlnp | grep 3000
检查防火墙设置
尝试通过 127.0.0.1:3000 而不是 localhost:3000 访问

AI 客户端无法连接：

确保端点 URL 正确
检查 MCPHub 是否在代理后面
验证 Kubernetes/Docker 环境中的网络策略

智能路由问题

数据库连接失败：

# 测试数据库连接
psql $DB_URL -c "SELECT 1;"

# 检查是否安装了 pgvector
psql $DB_URL -c "CREATE EXTENSION IF NOT EXISTS vector;"

嵌入服务错误：

验证 OpenAI API 密钥是否有效
检查互联网连接
监控速率限制

下一步

配置

配置您的 MCP 服务器和设置

快速开始

5分钟内启动并运行

服务器管理

了解如何管理您的 MCP 服务器

API 参考

探索完整的 API 文档

开始使用

核心功能

配置指南

先决条件

安装方法

Docker 安装

1. 基础安装

2. 使用自定义配置

3. 使用环境变量

4. Docker Compose

npm 包安装

1. 全局安装

2. 运行 MCPHub

本地开发环境设置

1. 克隆仓库

2. 安装依赖

3. 开发模式

4. 生产构建

5. 开发脚本

Kubernetes 部署

1. 设置的 ConfigMap

2. 部署

3. 服务

4. Ingress (可选)

智能路由设置 (可选)

先决条件

数据库设置

验证

控制台访问

故障排除

下一步

配置

快速开始

服务器管理

API 参考

​先决条件

​安装方法

​Docker 安装

​1. 基础安装

​2. 使用自定义配置

​3. 使用环境变量

​4. Docker Compose

​npm 包安装

​1. 全局安装

​2. 运行 MCPHub

​本地开发环境设置

​1. 克隆仓库

​2. 安装依赖

​3. 开发模式

​4. 生产构建

​5. 开发脚本

​Kubernetes 部署

​1. 设置的 ConfigMap

​2. 部署

​3. 服务

​4. Ingress (可选)

​智能路由设置 (可选)

​先决条件

​数据库设置

​验证

​控制台访问

​故障排除

​下一步

配置

快速开始

服务器管理

API 参考

先决条件

安装方法

Docker 安装

1. 基础安装

2. 使用自定义配置

3. 使用环境变量

4. Docker Compose

npm 包安装

1. 全局安装

2. 运行 MCPHub

本地开发环境设置

1. 克隆仓库

2. 安装依赖

3. 开发模式

4. 生产构建

5. 开发脚本

Kubernetes 部署

1. 设置的 ConfigMap

2. 部署

3. 服务

4. Ingress (可选)

智能路由设置 (可选)

先决条件

数据库设置

验证

控制台访问

故障排除

下一步