mcphub/docs/zh/quickstart.mdx

---
title: '快速开始指南'
description: '5 分钟内运行 MCPHub'
---

## 安装

<Tabs>
  <Tab title="Docker（推荐）">
    使用 Docker 是最快的开始方式：

    ```bash
    # 使用默认配置运行
    docker run -p 3000:3000 samanhappy/mcphub
    ```

    或者挂载自定义配置：

    ```bash
    # 使用自定义 MCP 设置运行
    docker run -p 3000:3000 \
      -v $(pwd)/mcp_settings.json:/app/mcp_settings.json \
      samanhappy/mcphub
    ```

  </Tab>
  <Tab title="本地开发">
    用于开发或自定义：

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

    # 安装依赖
    pnpm install

    # 启动开发服务器
    pnpm dev
    ```

    这会同时启动后端（端口 3001）和前端（端口 5173）的开发模式。

  </Tab>
  <Tab title="npm 包">
    将 MCPHub 安装为全局包：

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

    # 运行 MCPHub
    mcphub
    ```

  </Tab>
</Tabs>

## 初始设置

### 1. 访问控制面板

打开浏览器并导航到：

```
http://localhost:3000
```

### 2. 登录

使用默认凭据：

- **用户名**: `admin`
- **密码**: `admin123`

<Warning>为了安全起见，请在首次登录后立即更改这些默认凭据。</Warning>

### 3. 配置您的第一个 MCP 服务器

1. 在控制面板中点击 **"添加服务器"**
2. 输入服务器详细信息：
   - **名称**: 唯一标识符（例如 `fetch`）
   - **命令**: 可执行命令（`uvx`）
   - **参数**: 命令参数（`["mcp-server-fetch"]`）
   - **环境**: 任何所需的环境变量

fetch 服务器的示例配置：

```json
{
  "name": "fetch",
  "command": "uvx",
  "args": ["mcp-server-fetch"],
  "env": {}
}
```

## 基本使用

### 连接 AI 客户端

一旦配置了服务器，使用 MCPHub 端点连接您的 AI 客户端：

<Tabs>
  <Tab title="所有服务器">
    访问所有已配置的 MCP 服务器：``` http://localhost:3000/mcp ```
  </Tab>
  <Tab title="特定组">
    访问特定组中的服务器：``` http://localhost:3000/mcp/{groupName} ```
  </Tab>
  <Tab title="单个服务器">
    访问单个服务器：``` http://localhost:3000/mcp/{serverName} ```
  </Tab>
  <Tab title="智能路由">
    使用 AI 驱动的工具发现：``` http://localhost:3000/mcp/$smart ```
    <Info>智能路由需要使用 pgvector 的 PostgreSQL 和 OpenAI API 密钥。</Info>
  </Tab>
</Tabs>

### 示例：添加热门 MCP 服务器

以下是一些您可以添加的热门 MCP 服务器：

<AccordionGroup>
  <Accordion title="Web Fetch 服务器">
    ```json
    {
      "name": "fetch",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
    ```
  </Accordion>
  
  <Accordion title="Playwright 浏览器自动化">
    ```json
    {
      "name": "playwright",
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    }
    ```
  </Accordion>
  
  <Accordion title="高德地图（需要 API 密钥）">
    ```json
    {
      "name": "amap",
      "command": "npx",
      "args": ["-y", "@amap/amap-maps-mcp-server"],
      "env": {
        "AMAP_MAPS_API_KEY": "your-api-key-here"
      }
    }
    ```
  </Accordion>
  
  <Accordion title="Slack 集成">
    ```json
    {
      "name": "slack",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "your-bot-token",
        "SLACK_TEAM_ID": "your-team-id"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## 后续步骤

<CardGroup cols={2}>
  <Card title="服务器管理" icon="server" href="/zh/features/server-management">
    学习高级服务器配置和管理
  </Card>
  <Card title="组管理" icon="users" href="/zh/features/group-management">
    将服务器组织成逻辑组
  </Card>
  <Card title="智能路由" icon="route" href="/zh/features/smart-routing">
    设置 AI 驱动的工具发现
  </Card>
  <Card title="API 参考" icon="code" href="/zh/api-reference/introduction">
    探索完整的 API 文档
  </Card>
</CardGroup>

## 故障排除

<AccordionGroup>
  <Accordion title="服务器无法启动">
    - 检查 MCP 服务器命令是否在您的 PATH 中可访问
    - 验证环境变量是否正确设置
    - 检查 MCPHub 日志以获取详细错误信息
  </Accordion>

  <Accordion title="无法从 AI 客户端连接">
    - 确保 MCPHub 在正确的端口上运行
    - 检查防火墙设置
    - 验证端点 URL 格式
  </Accordion>

  <Accordion title="身份验证问题">
    - 验证凭据是否正确
    - 检查 JWT 令牌是否有效
    - 尝试清除浏览器缓存和 cookie
  </Accordion>
</AccordionGroup>

需要更多帮助？加入我们的 [Discord 社区](https://discord.gg/qMKNsn5Q) 获取支持！