/ 目录 / 演练场 / toolhive
● 社区 stacklok ⚡ 即开即用

toolhive

作者 stacklok · stacklok/toolhive

在隔离容器中运行 MCP server,一键安装,提供精选注册表、SSO 和 Kubernetes 支持。

ToolHive (Stacklok) 是企业级的 MCP server 运行平台。包含 Gateway + Registry + 容器 Runtime + Portal。面向团队和组织部署,提供最小权限的容器化 MCP、SSO、审计日志和精选目录。

为什么要用

核心特性

实时演示

实际使用效果

toolhive.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "toolhive": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/stacklok/toolhive"
      ],
      "_inferred": true
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "toolhive": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/stacklok/toolhive"
      ],
      "_inferred": true
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "toolhive": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/stacklok/toolhive"
      ],
      "_inferred": true
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "toolhive": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/stacklok/toolhive"
      ],
      "_inferred": true
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "toolhive",
      "command": "TODO",
      "args": [
        "See README: https://github.com/stacklok/toolhive"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "toolhive": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/stacklok/toolhive"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add toolhive -- TODO 'See README: https://github.com/stacklok/toolhive'

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: toolhive

如何安装社区 MCP 而不用信任随机的 `npx -y` 脚本

👤 注重安全的工程师 ⏱ ~10 min beginner

何时使用: 你想在本地运行 GitHub MCP,但不想给它不受限的文件系统访问权限。

前置条件
  • Docker Desktop — docker.com
  • ToolHive desktop 应用 — stacklok.com/download
步骤
  1. 打开 ToolHive,搜索注册表
    从 ToolHive 注册表中安装 'github'。✓ 已复制
    → 容器拉取完成,提示配置 GITHUB_TOKEN
  2. 自动配置你的客户端
    点击 'Connect to Claude Desktop'。✓ 已复制
    → Claude Desktop 配置已更新;需要重启
  3. 验证隔离
    确认容器只有你设置的环境变量,没有主机文件系统挂载。✓ 已复制
    → 在 ToolHive UI 中检查容器配置

结果: 一个沙箱化的 MCP,只有最小权限访问你的机器。

注意事项
  • 文件系统 MCP 需要挂载——默认无挂载太严格 — 添加限定范围的挂载(例如仅 ~/Projects),而不是完整主目录

如何在 Kubernetes 上为平台团队部署 MCP

👤 平台工程师 ⏱ ~60 min advanced

何时使用: 你希望实现组织范围内的 MCP 标准化部署。

前置条件
  • Kubernetes 集群 + cluster-admin — 已有的 EKS/GKE/AKS 或开发用的 kind
  • 安装 ToolHive Operator CRD — kubectl apply -f Stacklok 提供的 manifests
步骤
  1. 声明 MCPServer 资源
    kubectl apply -f mcp-github.yaml — 声明式注册一个 GitHub MCP,使用限定范围的凭据。✓ 已复制
    → Pod 运行中;Portal 中列出
  2. 通过 Portal 向用户公开
    工程师通过 SSO 登录 Portal,一键安装到他们的客户端。✓ 已复制
    → 自动生成每个用户的配置

结果: 中央目录 + 每个用户的安装配置;完全可审计。

注意事项
  • Stdio MCP 不适合网络暴露的 Kubernetes — 优先为 k8s 使用可流化的 HTTP MCP;对 stdio 使用 gateway

如何为所有 MCP 工具调用生成审计日志

👤 合规和安全团队 ⏱ ~30 min intermediate

何时使用: 你的组织需要记录'谁在什么时候调用了什么工具'以满足 SOC2 或内部政策要求。

步骤
  1. 启用 OpenTelemetry 导出
    在 ToolHive 设置中,将 OTLP endpoint 设置为你的 collector。✓ 已复制
    → 追踪数据出现在你的后端
  2. 按用户标记
    通过 SSO 启用每个用户的身份传播。✓ 已复制
    → 每个追踪都包含操作者 ID

结果: 按用户、按工具的审计日志。

组合

与其他 MCP 搭配,撬动十倍杠杆

toolhive + mcphub

使用 ToolHive 进行隔离,使用 MCPHub 进行多 server 路由

在各自的 ToolHive 容器中运行每个 MCP,并通过 MCPHub 组公开。✓ 已复制
toolhive + unla

将 ToolHive 运行的 MCP 与 Unla 的 REST-to-MCP 转换相结合

在 ToolHive 中注册我们的 Unla 转换的内部 API,实现容器化运行并支持 SSO。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
(platform) registry-install mcp_name 安装经过验证的 MCP free
(platform) gateway-proxy Transport + auth policy 用策略保护你的 MCP 前端 free
(platform) runtime-isolate Container spec 沙箱执行 free + infra cost

成本与限制

运行它的成本

API 配额
平台层没有 API 配额限制
每次调用 Token 数
最小的开销
费用
Desktop + CLI + 开源 Operator 免费。Enterprise 计划提供支持和合规性相关服务。
提示
从免费版本开始;只有在需要专门的 SLA 或高级 SSO/RBAC 时才升级。

安全

权限、密钥、影响范围

最小权限: 每个 MCP:最小权限环境变量和挂载 团队部署使用 SSO
凭据存储: ToolHive 内置的加密凭据管理器
数据出站: 由下游 MCP 决定;ToolHive 在配置时添加遥测
切勿授予: 不要自动授予超出每个 MCP 需求的文件系统挂载

故障排查

常见错误与修复

容器启动后立即退出

检查 MCP 的必需环境变量是否已设置(例如 GITHUB_TOKEN)。在 ToolHive UI 中查看日志。

安装后 Claude Desktop 找不到 server

重启 Claude Desktop — 配置更改仅在启动时加载。

K8s Operator CRD 安装失败

确保有 cluster-admin 权限且 k8s 版本满足 >= 1.27 的要求。

验证: kubectl version
OTLP 追踪缺失

Collector endpoint 必须接受 OTLP/HTTP 或 OTLP/gRPC;确认协议匹配。

替代方案

toolhive 对比其他方案

替代方案何时用它替代权衡
MCPHub你更需要多 server 聚合而不是容器隔离不以容器运行时为重点
Docker MCP Toolkit你倾向于使用 Docker 自己的集成工具注册表精选程度较低

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills