MCP 设置配置

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

配置文件概述

MCPHub 使用几个配置文件：

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

基本 MCP 设置结构

mcp_settings.json

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

示例配置

{
  "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 配置
`perSessionClient`	boolean	`false`	为每个下游 MCP 会话创建独立的上游客户端，而不是在所有会话间共享同一个连接。适用于 Playwright 等有状态服务器。参见会话级客户端隔离。

常见 MCP 服务器示例

Web 和 API 服务器

Fetch 服务器

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

使用 Playwright 进行网页抓取

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

会话级客户端隔离（有状态服务器）

默认情况下，MCPHub 为每个服务器仅保持一个上游连接，并在所有下游 MCP 会话间共享。对于有状态服务器来说，这意味着所有客户端共享同一份状态——以 Playwright 为例，每个会话都会操作同一个浏览器实例及其标签页。设置 perSessionClient: true 可以让 MCPHub 改为为每个下游会话创建独立的上游客户端。每个会话拥有各自的连接（对于 stdio 服务器，还会拥有各自的子进程），在首次工具调用时惰性创建，并在会话结束时自动销毁。

perSessionClient 是 MCPHub 侧的设置：它控制 MCPHub 打开多少个上游连接。它与 Playwright MCP 自身的 --isolated 标志不同，后者控制 Playwright 侧的浏览器配置隔离。二者天然互补——同时启用即可获得完全隔离的浏览器会话。

{
  "mcpServers": {
    "playwright": {
      "type": "streamable-http",
      "url": "http://playwright-mcp:3000/mcp",
      "perSessionClient": true
    }
  }
}

或者使用本地启动并带有 --isolated 标志的 Playwright MCP：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--isolated"],
      "perSessionClient": true
    }
  }
}

仅对真正持有会话级状态的服务器启用 perSessionClient。它会让上游连接（以及 stdio 子进程）数量随并发会话数成倍增长，因此对无状态服务器请保持关闭。

文件和系统服务器

文件系统服务器

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

SQLite 服务器

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

通信服务器

Slack 服务器

{
  "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}"
    }
  }
}

邮件服务器

{
  "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 服务器

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

Google Drive 服务器

{
  "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}"
    }
  }
}

地图和位置服务

高德地图服务器

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

OpenStreetMap 服务器

{
  "osm": {
    "command": "python",
    "args": ["-m", "mcp_server_osm"],
    "env": {
      "OSM_USER_AGENT": "MCPHub/1.0"
    }
  }
}

高级配置

环境变量替换

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

{
  "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} 指定默认值：

{
  "timeout": "${MCP_TIMEOUT:30000}",
  "maxRestarts": "${MCP_MAX_RESTARTS:5}"
}

条件配置

根据环境使用不同配置：

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

自定义服务器脚本

本地 Python 服务器

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

本地 Node.js 服务器

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

服务器元数据配置

servers.json

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

{
  "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"
    }
  }
}

组管理

组配置

{
  "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 支持配置热重载：

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

配置验证

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

{
  "validation": {
    "strict": true,
    "allowUnknownServers": false,
    "requireDocumentation": true
  }
}

工具结果压缩

MCPHub 可以在工具结果返回 MCP 客户端前，透明压缩较大的文本结果。它适合处理大型日志、diff、搜索输出、JSON 数组或长文本，避免这些内容占用过多模型上下文。工具结果压缩默认关闭。可以在 设置 → 工具结果压缩 中实时开关，也可以在 systemConfig.toolResultCompression 下配置：

{
  "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 压缩结果时会在文本开头加入类似下面的标记：

[mcphub:compressed-tool-result strategy=log original_tokens=9000 compressed_tokens=1200 omitted_lines=240]

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

最佳实践

安全

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

{
  "env": {
    "API_KEY": "${API_KEY}",
    "DATABASE_PASSWORD": "${DB_PASSWORD}"
  }
}

限制服务器权限：

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/restricted/path"],
    "env": {
      "READONLY": "true"
    }
  }
}

性能

设置适当的超时：

{
  "timeout": 30000,
  "maxRestarts": 3,
  "restartDelay": 5000
}

资源限制：

{
  "env": {
    "NODE_OPTIONS": "--max-old-space-size=512",
    "MEMORY_LIMIT": "512MB"
  }
}

监控

启用健康检查：

{
  "healthCheck": {
    "enabled": true,
    "interval": 30000,
    "timeout": 5000
  }
}

日志配置：

{
  "env": {
    "LOG_LEVEL": "info",
    "LOG_FORMAT": "json"
  }
}

故障排除

常见问题

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

# 手动测试命令
uvx mcp-server-fetch

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

# 检查环境
printenv | grep API_KEY

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

# 验证可执行权限
ls -la /path/to/server

调试配置

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

{
  "debug": {
    "enabled": true,
    "logLevel": "debug",
    "includeEnv": false,
    "logStartup": true
  }
}

验证错误

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

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

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

​MCP 设置配置

​配置文件概述

​基本 MCP 设置结构

​mcp_settings.json

​示例配置

​服务器配置选项

​必需字段

​可选字段

​常见 MCP 服务器示例

​Web 和 API 服务器

​Fetch 服务器

​使用 Playwright 进行网页抓取

​会话级客户端隔离（有状态服务器）

​文件和系统服务器

​文件系统服务器

​SQLite 服务器

​通信服务器

​Slack 服务器

​邮件服务器

​开发和 API 服务器

​GitHub 服务器

​Google Drive 服务器

​地图和位置服务

​高德地图服务器

​OpenStreetMap 服务器

​高级配置

​环境变量替换

​条件配置

​自定义服务器脚本

​本地 Python 服务器

​本地 Node.js 服务器

​服务器元数据配置

​servers.json

​组管理

​组配置

​访问控制

​动态配置

​热重载

​配置验证

​工具结果压缩

​最佳实践

​安全

​性能

​监控

​故障排除

​常见问题

​调试配置

​验证错误

MCP 设置配置

配置文件概述

基本 MCP 设置结构

mcp_settings.json

示例配置

服务器配置选项

必需字段

可选字段

常见 MCP 服务器示例

Web 和 API 服务器

Fetch 服务器

使用 Playwright 进行网页抓取

会话级客户端隔离（有状态服务器）

文件和系统服务器

文件系统服务器

SQLite 服务器

通信服务器

Slack 服务器

邮件服务器

开发和 API 服务器

GitHub 服务器

Google Drive 服务器

地图和位置服务

高德地图服务器

OpenStreetMap 服务器

高级配置

环境变量替换

条件配置

自定义服务器脚本

本地 Python 服务器

本地 Node.js 服务器

服务器元数据配置

servers.json

组管理

组配置

访问控制

动态配置

热重载

配置验证

工具结果压缩

最佳实践

安全

性能

监控

故障排除

常见问题

调试配置

验证错误