MCP 服务器

ToolHive - making MCP servers easy and secure

轻松安全地运行和管理 MCP 服务器

StacklokLabs

开发者工具

访问服务器

README

ToolHive - 让 MCP 服务器变得简单而安全

| | | |

ToolHive (thv) 是一个轻量级实用程序，旨在简化 MCP（模型上下文协议）服务器的部署和管理，确保易用性、一致性和安全性。

目录

为什么选择 ToolHive？
- 主要优势
快速开始
客户端兼容性
架构概览
使用示例
高级用法
- 自定义权限
- 在 Kubernetes 中运行 ToolHive
为 ToolHive 做贡献
许可证

为什么选择 ToolHive？

部署 MCP 服务器通常涉及复杂的多步骤流程，这可能会带来摩擦，例如运行可能不安全的命令（例如，uv 或 npx）、手动管理安全凭据（例如，以纯文本形式存储 API 令牌）以及处理不一致的打包方法。

ToolHive 旨在通过在一致且锁定的环境中运行容器来解决这些挑战，仅授予运行所需的最低权限。这大大减少了攻击面，提高了可用性，并强制执行容器安全的最佳实践。

ToolHive 通过关注三个关键领域来简化 MCP 部署：

易用性：使用 Docker 容器立即部署 MCP 服务器。通过一个简单的命令启动 MCP 服务器，而无需安装和管理不同版本的 Python、Node.js 或其他构建工具。
增强的安全性：默认情况下是安全的。 ToolHive 安全地管理密钥和配置，大大降低了泄漏的风险。避免在配置文件中使用纯文本密钥。
标准化打包：利用 OCI 容器标准为 MCP 服务器提供可重复、标准化的打包方法，确保兼容性和可靠性。

主要优势

精选的 MCP 注册表：ToolHive 提供了一个精选的 MCP 注册表，其中包含经过验证的配置，使您可以轻松地发现和部署 MCP 服务器。只需从列表中选择一个，然后使用一个命令安全地运行它。
企业级授权：专为企业环境设计的强大授权控制，安全地管理工具访问并与现有基础设施（例如，Kubernetes）无缝集成。
无缝集成：自动配置流行的开发工具，如 GitHub Copilot、Cursor 等，以简化您的工作流程。

快速开始

前提条件

ToolHive 目前可在 macOS 和 Linux 上使用 Docker 或 Podman。

对于客户端自动发现/配置，需要支持的客户端：

带有有效 GitHub Copilot 订阅的 VS Code（v1.99.0 或更高版本）
Cursor
Roo Code (VS Code 扩展)

安装

ToolHive 是用 Go 编写的 CLI 工具，并打包为单个二进制文件。您可以使用以下方法之一进行安装：

下载二进制文件

从 toolhive/releases 下载最新的跨平台发布二进制文件。

Homebrew (macOS)

使用 Homebrew 在 macOS 上安装：

brew tap stacklok/tap
brew install thv

从源代码构建

要从源代码构建 ToolHive，请克隆此存储库并使用 Go 构建 CLI：

go build ./cmd/thv
go install ./cmd/thv

或者使用 Task：

task build
task install

快速入门 - 运行您的第一个 MCP 服务器

注意：此示例启用自动发现以自动查找支持的客户端并更新其配置。如果您希望手动配置客户端，请跳过此步骤，或者运行 thv config register-client --help 以了解如何显式注册客户端。

# 启用客户端自动发现：
thv config auto-discovery true

# 运行 Fetch MCP 服务器，该服务器允许 LLM 获取网站内容：
thv run fetch

# 列出正在运行的 MCP 服务器：
thv list

您的客户端现在应该能够使用 fetch MCP 工具来获取网站内容。

客户端兼容性

ToolHive 已经过以下客户端的测试：

客户端	支持	备注
Copilot (VS Code)	✅	v1.99.0+ 或 Insiders 版本
Cursor	✅
Roo Code	✅
PydanticAI	✅
Continue	❌	Continue 尚不支持 SSE
Claude Desktop	❌	Claude Desktop 尚不支持 SSE

其他支持 SSE 协议的客户端和开发库也可以与 ToolHive 一起使用。

Copilot、Cursor 和 Roo Code 支持自动配置。对于其他客户端，需要手动配置 MCP 服务器 URL。

架构概览

ToolHive 公开一个 SSE 代理，以将请求转发到在容器中运行的 MCP 服务器。代理通过标准输入/输出 (stdio) 或服务器发送事件 (SSE) 与 MCP 服务器通信。

flowchart LR
  subgraph container[Docker/Podman]
    direction LR
    proxy1[SSE proxy 1]
    proxy2[SSE proxy 2]
    proxy3[SSE proxy 3]
    mcp1[MCP Server]
    mcp2[MCP Server]
    mcp3[MCP Server]

    proxy1 -->|stdio| mcp1
    proxy2 -->|stdio| mcp2
    proxy3 -->|sse| mcp3
  end

  T[ToolHive CLI] -->|Socket API| container
  C[Client] -->|HTTP/SSE| proxy1
  C[Client] -->|HTTP/SSE| proxy2
  C[Client] -->|HTTP/SSE| proxy3

使用示例

下面详细介绍了常见的使用场景。要查看所有可用的命令和选项，请参阅 ToolHive CLI 参考或运行 thv --help。

注册客户端

ToolHive 可以自动配置支持的客户端以使用您运行的 MCP 服务器。要利用此功能，必须先注册客户端，然后才能运行 MCP 服务器。

要启用对支持的客户端的自动发现和配置，请运行：

thv config auto-discovery true

或者，您可以手动注册客户端：

# 注册客户端
thv config register-client <client-name>

# 显示已注册的客户端
thv config list-registered-clients

# 删除客户端
thv config remove-client <client-name>

查找并运行 MCP 服务器

首先，找到您要运行的 MCP 服务器。您可以使用以下命令列出或搜索内置注册表中可用的 MCP 服务器：

# 列出所有可用的服务器
thv registry list

# 按关键字查找服务器
thv search <search-term>

要查看有关特定 MCP 服务器的详细信息，包括其可用工具、配置选项和其他元数据，请使用：

thv registry info <name-of-mcp-server>

找到要运行的 MCP 服务器后，使用 thv run 命令启动它：

thv run <name-of-mcp-server>

注册表已经包含运行服务器所需的所有参数，因此您无需指定任何其他参数。 ToolHive 将自动拉取镜像并启动服务器。

我们一直在努力扩展我们的 MCP 服务器注册表。如果您有希望包含的特定服务器，请随时打开一个 issue 或提交一个 pull request 以更新 registry.json 文件。

管理 MCP 服务器

要列出正在运行的 MCP 服务器：

thv list

这将显示由 ToolHive 管理的所有活动 MCP 服务器及其当前状态。要包括已停止的服务器，请添加 --all 标志。

要停止和/或删除服务器：

thv stop <name-of-mcp-server>
thv rm <name-of-mcp-server>

# 或者在一个命令中停止和删除：
thv rm -f <name-of-mcp-server>

密钥管理

许多 MCP 服务器需要 API 令牌或其他密钥进行身份验证。 ToolHive 提供了一种安全的方式来管理这些密钥，而无需在纯文本配置文件中公开它们。

此示例启用 ToolHive 的加密密钥存储，为 GitHub 身份验证令牌创建一个密钥，并使用该令牌运行 GitHub MCP 服务器：

thv config secrets-provider encrypted
thv secret set github
# <提示时输入您的 GitHub 个人访问令牌>

thv run --secret github,target=GITHUB_PERSONAL_ACCESS_TOKEN github

ToolHive 将加密密码存储在您操作系统的密钥链服务中。

有关管理密钥的更多详细信息，请参阅 thv secret 命令参考或运行 thv secret --help。

运行自定义 MCP 服务器

如果要运行注册表中没有的自定义 MCP 服务器，可以通过指定镜像名称和任何其他参数来执行此操作。例如：

thv run --transport sse --name my-mcp-server --port 8080 my-mcp-server-image:latest -- my-mcp-server-args

此命令与 docker run 非常相似，但侧重于安全性和简单性。调用时：

ToolHive 从指定的镜像 (my-mcp-server-image:latest) 创建一个容器。
它配置容器以侦听所选端口 (8080)。
标记容器，以便 ToolHive 可以跟踪它：
```
toolhive: true
toolhive-name: my-mcp-server
```
设置指定的传输方法 (--transport stdio 或 --transport sse)：
- 标准 I/O (stdio)，默认值：
  ToolHive 将来自客户端的 SSE 流量重定向到容器的标准输入和输出。这充当安全代理，确保容器无法直接访问网络或主机。
- 服务器发送事件 (SSE) (sse)：
  ToolHive 在一个随机端口上创建一个反向代理，该代理将请求转发到容器。这意味着容器本身不会直接公开任何端口。

使用协议方案运行 MCP 服务器

ToolHive 支持直接从包管理器使用协议方案运行 MCP 服务器。这允许您运行 MCP 服务器，而无需先构建和发布 Docker 镜像。

目前，支持两种协议方案：

uvx://: 对于使用 uv 包管理器的基于 Python 的 MCP 服务器
npx://: 对于使用 npm 的基于 Node.js 的 MCP 服务器

例如，要运行基于 Python 的 MCP 服务器：

thv run uvx://awslabs.core-mcp-server@latest

或者运行基于 Node.js 的 MCP 服务器：

thv run npx://pulumi/mcp-server@latest

当您使用协议方案时，ToolHive 将：

检测协议方案并提取包名称
基于适当的模板生成 Dockerfile
构建一个安装了该包的 Docker 镜像
使用构建的镜像运行 MCP 服务器

请注意，在这种情况下，您仍然可能需要指定其他参数，如传输方法、卷和环境变量。因此，该命令可能如下所示：

thv run --transport sse --name my-mcp-server --port 8080 uvx://some-sse-mcp-server@latest -- my-mcp-server-args

阅读特定 MCP 服务器的文档，以查看它是否需要任何其他参数。

高级用法

自定义权限

ToolHive 启动的容器具有最少的权限集，严格限制为所需的权限。可以通过使用 --permission-profile 标志提供的基于 JSON 的权限配置文件进一步自定义权限。

一个示例权限配置文件可能是：

{
  "read": ["/var/run/mcp.sock"],
  "write": ["/var/run/mcp.sock"],
  "network": {
    "outbound": {
      "insecure_allow_all": false,
      "allow_transport": ["tcp", "udp"],
      "allow_host": ["localhost", "google.com"],
      "allow_port": [80, 443]
    }
  }
}

此配置文件允许容器读取和写入 /var/run/mcp.sock Unix 套接字，并且还允许对端口 80 和 443 上的 localhost 和 google.com 发出出站网络请求。

为了方便起见，包括了两个内置配置文件：

stdio：授予最少的权限，没有网络访问权限。
network：允许对任何端口上的任何主机进行出站网络连接（不建议用于生产环境）。

在 Kubernetes 中运行 ToolHive

ToolHive 还可以用于在 Kubernetes 集群中部署 MCP 服务器。此功能仍在积极开发中，用于生产用例，但我们邀请您使用 kind 集群在本地试用它。

查看使用 kind 在 Kubernetes 中运行 ToolHive 指南以开始使用。

为 ToolHive 做贡献

我们欢迎为 ToolHive 做出贡献！如果您想贡献，请查看 CONTRIBUTING 指南，了解如何开始的详细信息。

如果您遇到错误或有功能请求，请在存储库中打开一个 issue 或加入我们的社区 Discord 服务器上的 #toolhive-developers 频道。

许可证

本项目根据 Apache 2.0 许可证获得许可。有关详细信息，请参阅 LICENSE 文件。