> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcphub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始指南

> 5 分钟内运行 MCPHub

## 安装

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

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

    或者挂载自定义配置：

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

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

    ```bash theme={null}
    # 克隆仓库
    git clone https://github.com/samanhappy/mcphub.git
    cd mcphub

    # 安装依赖
    pnpm install

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

    这会同时启动后端（端口 3000）和前端（端口 5173）的开发模式，Vite 开发服务器会把 API 与 MCP 请求代理到后端。
  </Tab>

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

    ```bash theme={null}
    # 全局安装
    npm install -g @samanhappy/mcphub

    # 运行 MCPHub
    mcphub
    ```
  </Tab>
</Tabs>

## 初始设置

### 1. 访问控制面板

打开浏览器并导航到：

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

### 2. 登录

默认用户名为 `admin`。首次启动时，如果未设置 `ADMIN_PASSWORD` 环境变量，系统将自动生成随机密码并输出到服务器日志中。

可以通过环境变量预先设置管理员密码：

```bash theme={null}
# 通过环境变量设置管理员密码
ADMIN_PASSWORD=your-secure-password docker run -p 3000:3000 samanhappy/mcphub
```

<Warning>首次登录后请及时修改管理员密码以确保安全。</Warning>

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

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

fetch 服务器的示例配置：

```json theme={null}
{
  "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 theme={null}
    {
      "name": "fetch",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
    ```
  </Accordion>

  <Accordion title="Playwright 浏览器自动化">
    ```json theme={null}
    {
      "name": "playwright",
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    }
    ```
  </Accordion>

  <Accordion title="高德地图（需要 API 密钥）">
    ```json theme={null}
    {
      "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 theme={null}
    {
      "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/c8GKyzyFF) 获取支持！