> ## 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.

# MCP 设置配置

> 配置 MCPHub 的 MCP 服务器及其设置

# MCP 设置配置

本指南说明如何使用 `mcp_settings.json` 文件和相关配置在 MCPHub 中配置 MCP 服务器。

## 配置文件概述

MCPHub 使用几个配置文件：

* **`mcp_settings.json`**：主要的 MCP 服务器配置
* **`servers.json`**：服务器元数据和分组
* **`.env`**：环境变量和密钥

## 基本 MCP 设置结构

### mcp\_settings.json

```json theme={null}
{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      },
      "cwd": "/working/directory",
      "timeout": 30000,
      "restart": true
    }
  }
}
```

### 示例配置

```json theme={null}
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": {
        "USER_AGENT": "MCPHub/1.0"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"],
      "timeout": 60000
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    }
  }
}
```

## 服务器配置选项

### 必需字段

| 字段        | 类型     | 描述       |
| --------- | ------ | -------- |
| `command` | string | 可执行命令或路径 |
| `args`    | array  | 命令行参数    |

### 可选字段

| 字段             | 类型      | 默认值             | 描述        |
| -------------- | ------- | --------------- | --------- |
| `env`          | object  | `{}`            | 环境变量      |
| `cwd`          | string  | `process.cwd()` | 工作目录      |
| `timeout`      | number  | `30000`         | 启动超时（毫秒）  |
| `restart`      | boolean | `true`          | 失败时自动重启   |
| `maxRestarts`  | number  | `5`             | 最大重启次数    |
| `restartDelay` | number  | `5000`          | 重启间延迟（毫秒） |
| `stdio`        | string  | `pipe`          | stdio 配置  |

## 常见 MCP 服务器示例

### Web 和 API 服务器

#### Fetch 服务器

```json theme={null}
{
  "fetch": {
    "command": "uvx",
    "args": ["mcp-server-fetch"],
    "env": {
      "USER_AGENT": "MCPHub/1.0",
      "MAX_REDIRECTS": "10"
    }
  }
}
```

#### 使用 Playwright 进行网页抓取

```json theme={null}
{
  "playwright": {
    "command": "npx",
    "args": ["@playwright/mcp@latest", "--headless"],
    "timeout": 60000,
    "env": {
      "PLAYWRIGHT_BROWSERS_PATH": "/tmp/browsers"
    }
  }
}
```

### 文件和系统服务器

#### 文件系统服务器

```json theme={null}
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
    "env": {
      "ALLOWED_OPERATIONS": "read,write,list"
    }
  }
}
```

#### SQLite 服务器

```json theme={null}
{
  "sqlite": {
    "command": "uvx",
    "args": ["mcp-server-sqlite", "--db-path", "/path/to/database.db"],
    "env": {
      "SQLITE_READONLY": "false"
    }
  }
}
```

### 通信服务器

#### Slack 服务器

```json theme={null}
{
  "slack": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
      "SLACK_TEAM_ID": "${SLACK_TEAM_ID}",
      "SLACK_APP_TOKEN": "${SLACK_APP_TOKEN}"
    }
  }
}
```

#### 邮件服务器

```json theme={null}
{
  "email": {
    "command": "python",
    "args": ["-m", "mcp_server_email"],
    "env": {
      "SMTP_HOST": "smtp.gmail.com",
      "SMTP_PORT": "587",
      "EMAIL_USER": "${EMAIL_USER}",
      "EMAIL_PASSWORD": "${EMAIL_PASSWORD}"
    }
  }
}
```

### 开发和 API 服务器

#### GitHub 服务器

```json theme={null}
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}
```

#### Google Drive 服务器

```json theme={null}
{
  "gdrive": {
    "command": "npx",
    "args": ["-y", "@google/mcp-server-gdrive"],
    "env": {
      "GOOGLE_CLIENT_ID": "${GOOGLE_CLIENT_ID}",
      "GOOGLE_CLIENT_SECRET": "${GOOGLE_CLIENT_SECRET}",
      "GOOGLE_REFRESH_TOKEN": "${GOOGLE_REFRESH_TOKEN}"
    }
  }
}
```

### 地图和位置服务

#### 高德地图服务器

```json theme={null}
{
  "amap": {
    "command": "npx",
    "args": ["-y", "@amap/amap-maps-mcp-server"],
    "env": {
      "AMAP_MAPS_API_KEY": "${AMAP_API_KEY}",
      "AMAP_LANGUAGE": "zh-cn"
    }
  }
}
```

#### OpenStreetMap 服务器

```json theme={null}
{
  "osm": {
    "command": "python",
    "args": ["-m", "mcp_server_osm"],
    "env": {
      "OSM_USER_AGENT": "MCPHub/1.0"
    }
  }
}
```

## 高级配置

### 环境变量替换

MCPHub 支持使用 `${VAR_NAME}` 语法进行环境变量替换：

```json theme={null}
{
  "mcpServers": {
    "api-server": {
      "command": "python",
      "args": ["-m", "api_server"],
      "env": {
        "API_KEY": "${API_KEY}",
        "API_URL": "${API_BASE_URL}/v1",
        "DEBUG": "${NODE_ENV:development}"
      }
    }
  }
}
```

可以使用 `${VAR_NAME:default}` 指定默认值：

```json theme={null}
{
  "timeout": "${MCP_TIMEOUT:30000}",
  "maxRestarts": "${MCP_MAX_RESTARTS:5}"
}
```

### 条件配置

根据环境使用不同配置：

```json theme={null}
{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["-m", "db_server"],
      "env": {
        "DB_URL": "${NODE_ENV:development == 'production' ? DB_URL : DEV_DB_URL}"
      }
    }
  }
}
```

### 自定义服务器脚本

#### 本地 Python 服务器

```json theme={null}
{
  "custom-python": {
    "command": "python",
    "args": ["./servers/custom_server.py"],
    "cwd": "/app/custom-servers",
    "env": {
      "PYTHONPATH": "/app/custom-servers",
      "CONFIG_FILE": "./config.json"
    }
  }
}
```

#### 本地 Node.js 服务器

```json theme={null}
{
  "custom-node": {
    "command": "node",
    "args": ["./servers/custom-server.js"],
    "cwd": "/app/custom-servers",
    "env": {
      "NODE_ENV": "production"
    }
  }
}
```

## 服务器元数据配置

### servers.json

使用服务器元数据补充 `mcp_settings.json`：

```json theme={null}
{
  "servers": {
    "fetch": {
      "name": "Fetch 服务器",
      "description": "用于网络请求的 HTTP 客户端",
      "category": "web",
      "tags": ["http", "api", "web"],
      "version": "1.0.0",
      "author": "MCPHub 团队",
      "documentation": "https://docs.mcphub.com/servers/fetch",
      "enabled": true
    },
    "playwright": {
      "name": "Playwright 浏览器",
      "description": "网页自动化和抓取",
      "category": "automation",
      "tags": ["browser", "scraping", "automation"],
      "version": "2.0.0",
      "enabled": true
    }
  },
  "groups": {
    "web-tools": {
      "name": "网页工具",
      "description": "用于网页交互的工具",
      "servers": ["fetch", "playwright"],
      "access": "public"
    },
    "admin-tools": {
      "name": "管理工具",
      "description": "管理实用程序",
      "servers": ["filesystem", "database"],
      "access": "admin"
    }
  }
}
```

## 组管理

### 组配置

```json theme={null}
{
  "groups": {
    "production": {
      "name": "生产工具",
      "description": "稳定的生产服务器",
      "servers": ["fetch", "slack", "github"],
      "access": "authenticated",
      "rateLimit": {
        "requestsPerMinute": 100,
        "burstLimit": 20
      }
    },
    "experimental": {
      "name": "实验功能",
      "description": "测试版和实验性服务器",
      "servers": ["experimental-ai", "beta-search"],
      "access": "admin",
      "enabled": false
    }
  }
}
```

### 访问控制

| 访问级别            | 描述           |
| --------------- | ------------ |
| `public`        | 无需认证         |
| `authenticated` | 需要有效的 JWT 令牌 |
| `admin`         | 需要管理员角色      |
| `custom`        | 自定义权限逻辑      |

## 动态配置

### 热重载

MCPHub 支持配置热重载：

```bash theme={null}
# 不重启重新加载配置
curl -X POST http://localhost:3000/api/admin/reload-config \
  -H "Authorization: Bearer your-admin-token"
```

### 配置验证

MCPHub 在启动和重新加载时验证配置：

```json theme={null}
{
  "validation": {
    "strict": true,
    "allowUnknownServers": false,
    "requireDocumentation": true
  }
}
```

## 工具结果压缩

MCPHub 可以在工具结果返回 MCP 客户端前，透明压缩较大的文本结果。它适合处理大型日志、diff、搜索输出、JSON 数组或长文本，避免这些内容占用过多模型上下文。

工具结果压缩默认关闭。可以在 **设置 → 工具结果压缩** 中实时开关，也可以在 `systemConfig.toolResultCompression` 下配置：

```json theme={null}
{
  "systemConfig": {
    "toolResultCompression": {
      "enabled": false,
      "minTokens": 2000,
      "maxOutputTokens": 1200,
      "strategy": "auto"
    }
  }
}
```

| 字段                | 类型                                                          | 默认值      | 描述                             |
| ----------------- | ----------------------------------------------------------- | -------- | ------------------------------ |
| `enabled`         | boolean                                                     | `false`  | 是否对成功的工具结果启用透明压缩。              |
| `minTokens`       | number                                                      | `2000`   | 单个文本块的估算 token 数达到或超过该阈值时才会压缩。 |
| `maxOutputTokens` | number                                                      | `1200`   | 每个压缩后文本块的目标 token 预算。          |
| `strategy`        | `"auto" \| "json" \| "log" \| "search" \| "diff" \| "text"` | `"auto"` | 压缩策略。`auto` 会自动识别常见结构化输出。      |

压缩只作用于成功的工具响应。带有 `isError: true` 的响应会原样返回，非文本内容块会被保留，每个文本块会独立判断是否需要压缩。MCPHub 压缩结果时会在文本开头加入类似下面的标记：

```text theme={null}
[mcphub:compressed-tool-result strategy=log original_tokens=9000 compressed_tokens=1200 omitted_lines=240]
```

活动日志仍记录上游工具的原始输出，压缩只发生在返回 MCP 客户端之前，因此运维人员仍可在 MCPHub 中查看完整结果。

## 最佳实践

### 安全

1. **对敏感数据使用环境变量**：

   ```json theme={null}
   {
     "env": {
       "API_KEY": "${API_KEY}",
       "DATABASE_PASSWORD": "${DB_PASSWORD}"
     }
   }
   ```

2. **限制服务器权限**：
   ```json theme={null}
   {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-filesystem", "/restricted/path"],
       "env": {
         "READONLY": "true"
       }
     }
   }
   ```

### 性能

1. **设置适当的超时**：

   ```json theme={null}
   {
     "timeout": 30000,
     "maxRestarts": 3,
     "restartDelay": 5000
   }
   ```

2. **资源限制**：
   ```json theme={null}
   {
     "env": {
       "NODE_OPTIONS": "--max-old-space-size=512",
       "MEMORY_LIMIT": "512MB"
     }
   }
   ```

### 监控

1. **启用健康检查**：

   ```json theme={null}
   {
     "healthCheck": {
       "enabled": true,
       "interval": 30000,
       "timeout": 5000
     }
   }
   ```

2. **日志配置**：
   ```json theme={null}
   {
     "env": {
       "LOG_LEVEL": "info",
       "LOG_FORMAT": "json"
     }
   }
   ```

## 故障排除

### 常见问题

**服务器无法启动**：检查命令和参数

```bash theme={null}
# 手动测试命令
uvx mcp-server-fetch
```

**找不到环境变量**：验证 `.env` 文件

```bash theme={null}
# 检查环境
printenv | grep API_KEY
```

**权限错误**：检查文件权限和路径

```bash theme={null}
# 验证可执行权限
ls -la /path/to/server
```

### 调试配置

启用调试模式进行详细日志记录：

```json theme={null}
{
  "debug": {
    "enabled": true,
    "logLevel": "debug",
    "includeEnv": false,
    "logStartup": true
  }
}
```

### 验证错误

常见验证错误和解决方案：

1. **缺少必需字段**：添加 `command` 和 `args`
2. **无效超时**：使用数字，不是字符串
3. **找不到环境变量**：检查 `.env` 文件
4. **找不到命令**：验证安装和 PATH

这个全面的指南涵盖了在 MCPHub 中为各种用例和环境配置 MCP 服务器的所有方面。