:deciduous_tree: MCPJungle :deciduous_tree:

为您的私有 AI 助手提供的自托管 MCP 网关

MCPJungle 是一个开源、自托管的网关，适用于您所有的 Model Context Protocol 服务器。

🧑‍💻 开发者使用它可以从一个中心位置注册和管理 MCP 服务器及其提供的工具。

🤖 MCP 客户端使用它可以从单个“网关”MCP 服务器发现并使用所有这些工具。

MCPJungle 是您的 AI 助手连接所需的唯一 MCP 服务器！

谁应该使用 MCPJungle？

1. 使用像 Claude 和 Cursor 这样的 MCP 客户端，并需要访问 MCP 服务器以进行工具调用的 开发者。
2. 构建生产级 AI 助手，并需要访问具有内置安全、隐私和访问控制功能的 MCP 服务器的 开发者。
3. 希望从一个中心位置查看和管理所有 MCP 客户端-服务器交互的 组织。托管在他们自己的数据中心 🔒

📋 目录

• 快速入门指南
• 安装
• 使用
  • 服务器
    • 在 Docker 中运行 MCPJungle 服务器
    • 直接在主机上运行 MCPJungle 服务器
    • 关闭服务器
  • 客户端
    • 添加可流式传输的 HTTP 基础 MCP 服务器
    • 添加基于 STDIO 的 MCP 服务器
    • 移除 MCP 服务器
    • 为服务器配置自定义 URL
  • 冷启动问题与状态保持连接
  • 从 Claude 连接到 MCPJungle
  • 从 Cursor 连接到 MCPJungle
  • 从 Copilot 连接到 MCPJungle
  • 全局启用/禁用工具
  • 提示
  • 工具组
  • 身份验证
  • 企业级功能
    • 访问控制
    • OpenTelemetry
• 局限性
• 贡献

快速入门指南

本快速入门指南将向您展示如何：

1. 使用 docker compose 在本地启动 MCPJungle 服务器。
2. 在 MCPJungle 中注册一个简单的 MCP 服务器。
3. 将您的 Claude 连接到 MCPJungle，以访问您的 MCP 工具。

启动服务器

curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.yaml
docker compose up -d

注册 MCP 服务器

在您的本地机器上，您可以使用 brew 或直接从 发布页面 下载 mcpjungle CLI。

brew install mcpjungle/mcpjungle/mcpjungle

该 CLI 允许您管理 MCPJungle 中的所有内容。

接下来，让我们使用 CLI 将一个 MCP 服务器添加到 MCPJungle 中。在此示例中，我们将使用 context7。

mcpjungle register --name context7 --url https://mcp.context7.com/mcp

连接到 MCPJungle

请在您的 Claude 的 MCP 服务器配置中使用以下设置：

{
  "mcpServers": {
    "mcpjungle": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp",
        "--allow-http"
      ]
    }
  }
}

一旦 MCPJungle 被添加为 Claude 的 MCP，您可以尝试向它提出以下请求：

使用 context7 获取 `/lodash/lodash` 的文档。

Claude 将会尝试通过 MCPJungle 调用 context7__get-library-docs 工具，从而返回 Lodash 库的文档。

恭喜您！🎉

您已成功在 MCPJungle 中注册了一个远程 MCP 服务器，并通过 Claude 调用了其中的一个工具。

现在您可以继续探索 MCPJungle，并查阅文档和 CLI 以获取更多详细信息。

安装

MCPJungle 以独立二进制文件的形式提供。

您可以从 发布页面 下载，也可以使用 Homebrew 进行安装：

brew install mcpjungle/mcpjungle/mcpjungle

通过运行以下命令验证您的安装：

mcpjungle version

[!重要] 在 macOS 上，您必须使用 Homebrew，因为编译后的二进制文件尚未获得 公证。

MCPJungle 提供了一个 Docker 镜像，可用于运行注册服务器（稍后会详细介绍）。

docker pull ghcr.io/mcpjungle/mcpjungle

使用

MCPJungle 采用客户端-服务器架构，该二进制文件允许您同时运行服务器和客户端。

服务器

MCPJungle 服务器负责管理所有在其内注册的 MCP 服务器，并为 AI 助手提供统一的 MCP 网关，以便发现和调用这些注册服务器所提供的工具。

该网关本身运行在可流式的 HTTP 传输之上，可通过 /mcp 端点访问。

在 Docker 中运行

要在本地运行 MCPJungle 服务器，推荐使用 docker compose：

# docker-compose.yaml 已针对个人在本地机器上出于个人用途运行 MCPJungle 进行优化。
# 默认情况下，MCPJungle 将以“开发”模式运行。
curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.yaml

docker compose up -d

# docker-compose.prod.yaml 则针对希望在远程服务器上部署 MCPJungle 以供多用户使用的组织进行了优化。

# mcpjungle 默认将以 `enterprise` 模式运行，该模式启用了企业级功能。
curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.prod.yaml

docker compose -f docker-compose.prod.yaml up -d

[!NOTE] enterprise 模式以前称为 production 模式。 为了更清晰地表达，该模式现已更名为 enterprise。其他方面保持不变。

这将启动 MCPJungle 服务器以及一个持久化的 Postgres 数据库容器。

您可以快速验证服务器是否正在运行：

curl http://localhost:8080/health

如果您计划注册依赖 npx 或 uvx 的基于 stdio 的 MCP 服务器，请改用 mcpjungle 的 stdio 标签 Docker 镜像。

MCPJUNGLE_IMAGE_TAG=latest-stdio docker compose up -d

[!NOTE] 如果您使用的是 docker-compose.yaml，那么默认镜像标签已经是 stdio。 只有在使用 docker-compose.prod.yaml 时，才需要指定 stdio 镜像标签。

此镜像体积较大。但在本地运行依赖 stdio 的 MCP 服务器时，它非常方便且推荐使用。

例如，如果您只想注册 context7 和 deepwiki 等远程 MCP 服务器，可以使用标准（最小）镜像。

但如果您还想使用 filesystem、time、github 等基于 stdio 的服务器，则应改用 stdio 标签的镜像。

[!NOTE] 如果您的 stdio 服务器依赖于 npx 或 uvx 之外的工具，您需要创建一个自定义 Docker 镜像，其中包含这些依赖项以及 mcpjungle 二进制文件。

生产部署

默认的 MCPJungle Docker 镜像 非常轻量——它仅包含一个最小的基础镜像和 mcpjungle 二进制文件。

因此，它非常适合并推荐用于生产环境部署。

对于数据库，我们建议您部署一个独立的 Postgres 数据库集群，并将其端点提供给 mcpjungle（请参阅下方的 [数据库] 部分）。

您可以查看 标准 Docker 镜像 和 stdio Docker 镜像 的定义。

直接在主机上运行

您也可以直接在主机上使用二进制文件运行服务器：

mcpjungle start

这将启动主注册中心服务器和 MCP 网关，默认在端口 8080 上可访问。

关闭

让 mcpjungle 服务器优雅地关闭非常重要，以确保正确清理资源。

停止服务器进程的推荐方法是向其发送 SIGTERM 信号。

数据库

MCPJungle 服务器依赖于数据库，默认会在当前工作目录下创建一个 SQLite 数据库文件 mcpjungle.db。

当您只是在本地测试时，这样做是可以的。

对于更正式的部署，MCPJungle 也支持 PostgreSQL。您可以提供 DSN 来连接到它：

# 您可以将数据库 DSN 作为环境变量提供
export DATABASE_URL=postgres://admin:root@localhost:5432/mcpjungle_db

# 以容器方式运行
docker run ghcr.io/mcpjungle/mcpjungle:latest

# 或者直接运行
mcpjungle start

如果您不喜欢使用 DSN，也可以提供特定于 PostgreSQL 的环境变量或文件：

# 如果使用特定于 PostgreSQL 的环境变量，host 是必填项
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432

export POSTGRES_USER=admin
export POSTGRES_USER_FILE=/path/to/user-file

export POSTGRES_PASSWORD=secret
export POSTGRES_PASSWORD_FILE=/path/to/password-file

export POSTGRES_DB=mcpjungle_db
export POSTGRES_DB_FILE=/path/to/db-file

mcpjungle start

客户端

一旦服务器启动，您就可以使用 mcpjungle CLI 与其交互。

MCPJungle 目前支持使用 stdio 和 可流式 HTTP 传输协议的 MCP 服务器。

[!NOTE] 对 SSE（服务器推送事件）的支持也存在，但目前尚未成熟。

下面我们来看看如何在 MCPJungle 中注册它们。

注册基于可流式 HTTP 的服务器

假设您已经在本地运行了一个可流式 HTTP 的 MCP 服务器，地址为 http://127.0.0.1:8000/mcp，它提供了诸如 add、subtract 等基本数学工具。

您可以将此 MCP 服务器注册到 MCPJungle 中：

mcpjungle register --name calculator --description "提供一些基本数学工具" --url http://127.0.0.1:8000/mcp

如果您使用 Docker Compose 运行该服务器，并且不在 Linux 系统上，那么您需要使用 host.docker.internal 而不是本地回环地址。

mcpjungle register --name calculator --description "提供一些基本数学工具" --url http://host.docker.internal:8000/mcp

现在，注册中心将开始跟踪该 MCP 服务器并加载其工具。

您也可以通过配置文件来注册 MCP 服务器：

cat ./calculator.json
{
  "name": "calculator",
  "transport": "streamable_http",
  "description": "提供一些基本数学工具",
  "url": "http://127.0.0.1:8000/mcp"
}

mcpjungle register -c ./calculator.json

该服务器提供的所有工具现在都可以通过 MCPJungle 访问：

mcpjungle list tools

# 查看工具使用方法
mcpjungle usage calculator__multiply

# 调用工具
mcpjungle invoke calculator__multiply --input '{"a": 100, "b": 50}'

[!NOTE] 在 MCPJungle 中，工具必须使用规范名称来引用，其格式为 <mcp-服务器名>__<工具名>。 服务器名和工具名之间用双下划线 __ 分隔。

例如，如果您注册了一个名为 github 的 MCP 服务器，它提供了一个名为 git_commit 的工具，那么您可以在 MCPJungle 中使用名称 github__git_commit 来调用该工具。

您的 MCP 客户端也必须使用此规范名称通过 MCPJungle 调用工具。

注册基于可流式 HTTP 的 MCP 服务器的配置文件格式如下：

{
  "name": "<您的 MCP 服务器名称>",
  "transport": "streamable_http",
  "description": "<描述>",
  "url": "<MCP 服务器的 URL>",
  "bearer_token": "<可选的身份验证 Bearer 令牌>",
  "headers": {
    "<自定义 HTTP 头>": "<值>"
  }
}

注册基于 STDIO 的服务器

以下是一个示例配置文件（我们称之为 filesystem.json），用于一个使用 STDIO 传输协议的 MCP 服务器：

{
  "name": "filesystem",
  "transport": "stdio",
  "description": "文件系统 MCP 服务器",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}

您可以通过提供此配置文件将该 MCP 服务器注册到 MCPJungle 中：

mcpjungle register -c ./filesystem.json

# 将 JSON 配置保存到文件（例如 filesystem.json）
mcpjungle 注册 -c ./filesystem.json

用于注册基于 STDIO 的 MCP 服务器的配置文件格式如下：

{
  "name": "<你的 MCP 服务器名称>",
  "transport": "stdio",
  "description": "<描述>",
  "command": "<运行 MCP 服务器的命令，例如 'npx'、'uvx'>",
  "args": ["传递给命令的", "参数", "列表"],
  "env": {
    "KEY": "value"
  }
}

你也可以观看关于如何注册基于 STDIO 的 MCP 服务器的简短视频。

[!提示] 如果你的 STDIO 服务器因某种原因失败或抛出错误，请检查 mcpjungle 服务器的日志以查看其 stderr 输出。

JSON 配置文件中的环境变量

当你使用 JSON 配置文件来注册 MCP 服务器或创建其他实体（如 tol 组）时，CLI 可以在将请求发送到服务器之前解析字符串值中的环境变量占位符。

• 只有以 ${VAR_NAME} 格式的占位符会被解析。
• 占位符可以出现在字符串值的任何位置，例如 prefix-${VAR_NAME}-suffix。
• 解析过程在 CLI 进程中进行，因此必须在你运行命令的地方可用该环境变量。
• 如果引用的环境变量未设置，则命令会失败并报错。
• 这适用于 JSON 配置中的所有字符串字段，包括嵌套对象和字符串数组。

MCP 服务器配置示例：

{
  "name": "affine-main",
  "transport": "streamable_http",
  "description": "AFFiNE 工作区 MCP 服务器",
  "url": "https://app.affine.pro/api/workspaces/${AFFINE_WORKSPACE_ID}/mcp",
  "bearer_token": "${AFFINE_API_TOKEN}",
  "headers": {
    "X-Workspace": "${AFFINE_WORKSPACE_ID}"
  }
}

STDIO 配置示例：

{
  "name": "my-stdio-server",
  "transport": "stdio",
  "command": "uvx",
  "args": ["my-server", "--workspace", "${WORKSPACE_ID}"],
  "env": {
    "API_TOKEN": "${API_TOKEN}"
  }
}

注意事项 ⚠️

当在 Docker 容器中运行 mcpjungle 时，你需要一些额外的配置才能运行 filesystem MCP 服务器。

默认情况下，容器内的 mcpjungle 无法访问宿主机的文件系统。

因此，你必须：

• 将你想要访问的宿主机目录作为卷挂载到容器中
• 在 filesystem MCP 服务器的命令参数中指定该挂载路径为目录

mcpjungle 提供的 docker-compose.yaml 文件会将当前工作目录挂载为容器中的 /host。

因此，你可以使用以下配置来运行 filesystem MCP 服务器：

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/host"]
}

这样，mcp 就可以访问 /host，即你宿主机上的当前工作目录。

更多详细信息请参阅 DEVELOPMENT.md。

从 Docker 或 Kubernetes 部署中运行 CLI 命令

如果你的 MCPJungle 服务器正在远程的 Docker 容器或 Kubernetes 集群中运行，你也可以直接在容器内执行 mcpjungle 二进制文件：

docker exec -it <容器名称> /mcpjungle
kubectl -n <命名空间> exec -it po/<Pod 名称> -- /mcpjungle

[!注意] 标准镜像不包含 shell。请通过 docker exec 或 kubectl exec 直接运行 /mcpjungle。

这在与服务器运行在同一环境中执行 CLI 命令时非常有用。

注销 MCP 服务器

你可以从 mcpjungle 中移除一个 MCP 服务器。

mcpjungle 注销 calculator
mcpjungle 注销 filesystem

一旦移除，该 MCP 服务器及其工具将不再对你或你的 MCP 客户可用。

配置自定义注册表 URL

默认情况下，CLI 会连接到 http://127.0.0.1:8000 上的 mcpjungle 服务器。

如果你的服务器运行在不同的主机或端口上（例如远程部署），你可以通过两种方式配置注册表 URL：

选项 1：使用 --registry 标志

mcpjungle --registry http://my-server:9000 列举工具

选项 2：在配置文件中设置

创建或编辑 ~/.mcpjungle.conf：

registry_url: http://my-server:9000

这样可以避免每次命令都传递 --registry 标志。

冷启动问题与有状态连接

默认情况下，每当调用工具时，MCPJungle 都会与上游 MCP 服务器建立一个新的连接。

工具调用完成后，连接就会关闭。

这样做可以保持系统的整洁，并避免内存泄漏。

但有时这会导致延迟开销。例如，每次调用基于 STDIO 的 MCP 服务器的工具时，都会启动一个新的进程。如果服务器需要几秒钟才能启动，这会减慢工具调用和整体交互的速度。

为了解决这个问题，MCPJungle 也支持有状态连接。

你可以在 MCP 服务器配置中将 session_mode 设置为 stateful（默认是 stateless）：

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
  "session_mode": "stateful"
}

mcpjungle 会在第一次调用该服务器的工具时与其建立一个新的连接。

工具调用完成后，这个连接不会关闭。后续对该服务器的工具调用将复用同一个连接，从而避免冷启动的开销。

连接仅在以下情况下才会关闭：

1. mcpjungle 服务器停止运行
2. MCP 服务器从 mcpjungle 中注销
3. 连接在一段时间无活动后超时。你可以使用 SESSION_IDLE_TIMEOUT_SEC 环境变量来全局配置 mcpjungle 服务器的超时时间（默认值为 -1，表示无超时）。

在可能的情况下，建议使用无状态连接（默认设置）。

与其他 MCP 客户端的集成

假设 MCPJungle 正在 http://localhost:8080 上运行，可以使用以下配置连接到它：

Claude

{
  "mcpServers": {
    "mcpjungle": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp",
        "--allow-http"
      ]
    }
  }
}

Cursor

{
  "mcpServers": {
    "mcpjungle": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

你还可以观看关于如何将 Cursor 连接到 MCPJungle的简短视频。

Copilot

请按照 Copilot 的文档中关于手动配置 MCP 服务器的部分操作。

在将 mcpjungle 添加到你的 mcp.json 配置文件后，应如下所示：

{
  "servers": {
    "mcpjungle": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

[!注意] 你可能需要点击 开始 按钮，Copilot 才能真正开始与 mcpjungle 交互。

启用/禁用工具

您可以禁用并重新启用特定工具，或 MCP 服务器提供的所有工具。

如果某个工具被禁用，则它将无法通过 MCPJungle 代理或任何工具组访问，因此任何 MCP 客户端都无法查看或调用该工具。

您还可以禁用和启用提示（Prompts）。

# 禁用由 `context7` MCP 服务器提供的 `get-library-docs` 工具
mcpjungle disable tool context7__get-library-docs

# 重新启用该工具
mcpjungle enable tool context7__get-library-docs

# 禁用 context7 中的所有工具
mcpjungle disable tool context7

# 禁用整个 `context7` MCP 服务器（禁用所有工具和提示）
mcpjungle disable server context7

# 重新启用 `context7`
mcpjungle enable server context7

# 禁用一个提示
mcpjungle disable prompt "huggingface_Model Details"

# 禁用 context7 中的所有提示
mcpjungle disable prompt context7

被禁用的工具仍然可以通过 mcpjungle 的 HTTP API 访问，因此管理员仍可通过命令行（或其他 HTTP 客户端）对其进行管理。

[!NOTE] 当新服务器注册到 MCPJungle 时，其所有工具和提示默认均为启用状态。

提示（Prompts）

Mcpjungle 支持 提示。

当您注册新的 MCP 服务器时，如果该服务器提供提示，则这些提示也会在 MCPJungle 中注册。

以下是一些使用命令行与提示交互的示例：

# 列出 huggingface MCP 服务器提供的所有提示
$ mcpjungle list prompts --server huggingface

# 获取“模型详情”提示，并传入自定义参数
$ mcpjungle get prompt "huggingface__Model Details" --arg model_id="openai/gpt-oss-120b"

工具组

随着您向 MCPJungle 添加更多 MCP 服务器，网关可用的工具数量可能会显著增加。

如果您的 MCP 客户端通过网关接触到数百个工具，其性能可能会下降。

MCPJungle 允许您使用工具组仅向您的 MCP 客户端暴露部分可用工具。

您可以创建一个新的工具组，并仅包含您希望公开的特定工具。

一旦创建了工具组，mcpjungle 将为其返回一个唯一的端点。

然后您可以配置您的 MCP 客户端，使其使用此特定于工具组的端点，而不是主网关端点。

创建工具组

您可以通过向 create group 命令提供一个 JSON 配置文件来创建新的工具组。

您必须为该组指定一个唯一的名称，并使用以下一个或多个字段来定义要包含哪些工具：

• included_tools：列出要包含的具体工具名称（例如：["filesystem__read_file", "time__get_current_time"]）
• included_servers：包含特定 MCP 服务器中的所有工具（例如：["time", "deepwiki"]）
• excluded_tools：排除特定工具（在包含整个服务器时非常有用）

示例 1：精选特定工具

以下是工具组配置文件 (claude-tools-group.json) 的示例：

{
  "name": "claude-tools",
  "description": "该组仅包含 Claude Desktop 可使用的工具",
  "included_tools": [
    "filesystem__read_file",
    "deepwiki__read_wiki_contents",
    "time__get_current_time"
  ]
}

该组仅公开 3 个精心挑选的工具，而不是所有可用工具。

示例 2：包含整个服务器并排除部分工具

您也可以包含特定服务器中的所有工具，并选择性地排除某些工具：

{
  "name": "claude-tools",
  "description": "包含 time 和 deepwiki 服务器的所有工具，但排除 time__convert_time",
  "included_servers": ["time", "deepwiki"],
  "excluded_tools": ["time__convert_time"]
}

这将包含 time 和 deepwiki 服务器中的所有工具，但会排除 time__convert_time。

示例 3：混合使用多种方法

您还可以结合使用所有三个字段以获得最大的灵活性：

{
  "name": "comprehensive-tools",
  "description": "手动选择工具、包含整个服务器并排除部分工具的组合",
  "included_tools": ["filesystem__read_file"],
  "included_servers": ["time"],
  "excluded_tools": ["time__convert_time"]
}

这将包含 filesystem__read_file 以及 time 服务器中的所有工具，但会排除 time__convert_time。

您可以在 mcpjungle 中创建此工具组：

$ mcpjungle create group -c ./claude-tools-group.json

工具组 claude-tools 已成功创建。
现在可通过以下可流式传输的 HTTP 端点访问：

    http://127.0.0.1:8080/v0/groups/claude-tools/mcp

然后您可以配置 Claude（或任何其他 MCP 客户端），使其使用此特定于工具组的端点来访问 MCP 服务器。

客户端将只能看到并使用这 3 个工具，而不会意识到 MCPJungle 中注册的其他任何工具。

[!TIP] 您可以运行 mcpjungle list tools 来查看所有可用工具，并选择您想要包含在组中的工具。

您还可以观看关于使用工具组的视频。

[!NOTE] 排除操作始终在最后执行。 因此，如果您将某个工具同时添加到 included_tools 并将其列入 excluded_tools，则该工具最终仍将被排除在组外。

局限性 🚧

目前工具组不支持提示。我们正在努力修复此问题 🛠️

管理工具组

目前您可以执行列出所有工具组、查看特定工具组详细信息以及删除工具组等操作。

# 列出所有工具组
mcpjungle list groups

# 查看特定工具组的详细信息
mcpjungle get group claude-tools

# 删除工具组
mcpjungle delete group claude-tools

在工具组中使用工具

您可以使用 --group 标志在特定工具组中列出和调用工具：

# 列出特定工具组中的工具
mcpjungle list tools --group claude-tools

# 从特定工具组上下文中调用工具
mcpjungle invoke filesystem__read_file --group claude-tools --input '{"path": "README.md"}'

这些命令提供了基于工具组的作用域操作，使您能够更轻松地在特定上下文中使用工具，并验证工具是否确实存在于您的工具组中。

[!NOTE] 如果某个工具被包含在工具组中，但随后在全球范围内被禁用或删除，则它将无法通过该工具组的 MCP 端点访问。 然而，如果该工具稍后被重新启用或再次添加，则它将自动重新出现在该工具组中。

局限性 🚧

1. 目前您无法更新现有的工具组。您必须删除该组，并使用修改后的配置文件创建一个新的工具组。
2. 在 enterprise 模式下，目前只有管理员可以创建工具组。我们正在努力允许普通用户也能创建自己的工具组。

身份验证

MCPJungle 目前支持身份验证，前提是您的 Streamable HTTP MCP 服务器接受用于身份验证的静态令牌。

这在使用 SaaS 提供的 MCP 服务器时非常有用，例如 HuggingFace、Stripe 等，这些服务器需要您的 API 令牌进行身份验证。

您可以在注册 MCP 服务器时提供您的令牌：

# 如果您指定了 `--bearer-token` 标志，MCPJungle 会在发送到此 MCP 服务器的所有请求中添加 `Authorization: Bearer <token>` 头。
mcpjungle register --name huggingface --description "HuggingFace MCP Server" --url https://huggingface.co/mcp --bearer-token <your-hf-api-token>

或者从您的配置文件中：

{
  "name": "huggingface",
  "transport": "streamable_http",
  "url": "https://huggingface.co/mcp",
  "description": "hugging face mcp server",
  "bearer_token": "<your-hf-api-token>"
}

如果您需要为 Authorization 头部提供自定义值，或添加其他自定义头部，可以在配置文件中使用 headers 字段：

{
  "name": "sourcegraph",
  "transport": "streamable_http",
  "url": "https://sourcegraph.mycompany.com/.api/mcp",
  "headers": {
    "Authorization": "token <your-sourcegraph-token>",
    "Custom-Header": "custom-value"
  }
}

Oauth 流程的支持即将推出！

企业级功能 🔒

如果您在组织内运行 MCPJungle，我们建议以 enterprise 模式运行服务器：

# 通过 enterprise 模式启用企业级功能
mcpjungle start --enterprise

# 您也可以将服务器模式指定为环境变量（有效值为 `development` 和 `enterprise`）
export SERVER_MODE=enterprise
mcpjungle start

# 或者使用上文所述的企业级 Docker Compose 文件
docker compose -f docker-compose.prod.yaml up -d

默认情况下，mcpjungle 服务器以 development 模式运行，这非常适合个人在本地运行。

在 Enterprise 模式下，服务器会实施更严格的安全策略，并提供额外的功能，如身份验证、ACL、可观ability 等。

以 enterprise 模式启动服务器后，您必须在客户端机器上运行以下命令来初始化服务器：

mcpjungle init-server

这将在服务器中创建一个管理员用户，并将其 API 访问令牌存储在您的主目录中（~/.mcpjungle.conf）。

然后您可以使用 mcpjungle CLI 向服务器发出经过身份验证的请求。

访问控制

在 development 模式下，所有 MCP 客户端都可以完全访问 MCPJungle Proxy 中注册的所有 MCP 服务器。

而在 enterprise 模式下，您可以控制哪些 MCP 客户端可以访问哪些 MCP 服务器。

假设您已在 enterprise 模式下的 MCPJungle 中注册了两个 MCP 服务器 calculator 和 github。

默认情况下，没有任何 MCP 客户端可以访问这些服务器。您必须在 mcpjungle 中创建一个 MCP 客户端，并显式允许其访问这些 MCP 服务器。

# 为您的 Cursor IDE 创建一个新的 MCP 客户端，使其能够访问 calculator 和 github MCP 服务器
mcpjungle create mcp-client cursor-local --allow "calculator, github"

MCP 客户端 'cursor-local' 已成功创建！
可访问的服务器：calculator, github

访问令牌：1YHf2LwE1LXtp5lW_vM-gmdYHlPHdqwnILitBhXE4Aw
请在 `Authorization: Bearer {token}` HTTP 头部中发送此令牌。

Mcpjungle 会为您的客户端生成一个访问令牌。请配置您的客户端或代理，在向 mcpjungle 代理发送请求时，将此令牌包含在 Authorization 头部中。

[!TIP] 您还可以使用 --access-token 标志为您的 MCP 客户端和用户账户提供自定义访问令牌。这在您希望自行管理令牌时很有用，例如通过中央身份服务器。

例如，您可以在 Cursor 中添加以下配置以连接到 MCPJungle：

{
  "mcpServers": {
    "mcpjungle": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer 1YHf2LwE1LXtp5lW_vM-gmdYHlPHdqwnILitBhXE4Aw"
      }
    }
  }
}

以这种方式获得特定服务器访问权限的客户端，可以查看并调用该服务器提供的所有工具。

[!NOTE] 如果您未指定 --allow 标志，该 MCP 客户端将无法访问任何 MCP 服务器。

从配置文件创建 MCP 客户端

您也可以通过提供 JSON 配置文件来创建 MCP 客户端：

{
	"name": "foobar",
	"allowed_servers": ["deepwiki", "time"],
	"access_token": "my_secret_token_123",
    "access_token_ref": {
        "file": "/path/to/token-file.txt",
        "env": "ENV_VAR_NAME"
    }
}

从配置文件创建客户端时，必须提供自定义访问令牌，因为 mcpjungle 无法将生成的令牌打印到控制台。

在配置文件中提供自定义访问令牌

从配置文件中提供访问令牌有三种方式：

1. 直接在 access_token 字段中：仅用于测试目的。不建议在生产环境中使用，尤其是在您将配置文件提交到版本控制系统时。
2. 使用 access_token_ref.file 字段从文件中读取：文件中应仅包含令牌字符串。
3. 使用 access_token_ref.env 字段从环境变量中读取：环境变量中应包含令牌字符串。

您还可以在同一 JSON 配置文件中的其他位置使用 ${VAR_NAME} 占位符。例如：

{
  "name": "${MCP_CLIENT_NAME}",
  "allowed_servers": ["${PRIMARY_SERVER}", "time"],
  "access_token_ref": {
    "env": "CLIENT_TOKEN_ENV_NAME"
  }
}

创建用户账户

除了 MCP 客户端之外，您还可以在 mcpjungle 中为人类用户创建用户账户。

与 enterprise 模式下的管理员相比，用户的权限非常有限。例如，他们可以查看和使用 MCP 服务器，但没有在 mcpjungle 中的写入权限。

# 自动为用户生成一个秘密
mcpjungle create user bob
# 为用户指定自定义访问令牌
mcpjungle create user alice --access-token alice_token_123
# 从配置文件创建用户
mcpjungle create user --conf /path/to/user-config.json

创建用户时使用的配置文件格式与创建 MCP 客户端时类似：

{
    "name": "charlie",
    "access_token": "charlies_secret_token",
    "access_token_ref": {
        "file": "/path/to/token-file.txt",
        "env": "ENV_VAR_NAME"
    }
}

同样，使用配置文件时，必须提供自定义访问令牌。

与 mcpjungle 中的其他 JSON 配置文件一样，用户配置文件也支持在字符串字段中使用 ${VAR_NAME} 占位符。

OpenTelemetry

MCPJungle 支持与 Prometheus 兼容的 OpenTelemetry 指标，用于可观ability。

• 在 enterprise 模式下，OpenTelemetry 默认启用。
• 在 development 模式下，遥测默认禁用。您可以通过在启动服务器之前将 OTEL_ENABLED 环境变量设置为 true 来启用它：

# 启用 OpenTelemetry 指标
export OTEL_ENABLED=true

# 可选地，设置要添加到所有指标的额外属性
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=enterprise

# 启动服务器
mcpjungle start

一旦 mcpjungle 服务器启动，指标就可以在 /metrics 端点访问了。

当前限制 🚧

我们还不完美，但正在努力改进！

1. MCPJungle 目前尚不支持 OAuth 流程进行身份验证

这仍在开发中。

我们正在收集更多关于用户如何将 OAuth 与 MCP 服务器一起使用的信息，因此欢迎发起讨论或提交问题，分享您的使用场景。

贡献 💻

我们欢迎社区的贡献！

• 有关贡献指南和规范，请参阅 CONTRIBUTION.md
• 有关开发环境搭建和技术细节，请参阅 DEVELOPMENT.md

加入我们的 Discord 社区，与其他贡献者和维护者交流互动。

MCPJungle 快速上手指南

MCPJungle 是一个开源的、可自托管的 MCP（Model Context Protocol）网关。它允许开发者在一个中心位置注册和管理多个 MCP 服务器，并让 AI 代理（如 Claude、Cursor）通过连接这一个网关来发现和使用所有已注册的工具。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: macOS, Linux 或 Windows (需支持 Docker)。
  • 注意: 在 macOS 上，由于二进制文件尚未公证，强烈建议通过 Homebrew 安装。
• 运行时依赖:
  • Docker & Docker Compose: 推荐用于快速部署服务端（最简便方式）。
  • Node.js: 如果需要在本地直接运行二进制文件或作为客户端连接，建议安装。
• 网络要求: 确保端口 8080 未被占用（默认服务端口）。

安装步骤

MCPJungle 采用客户端 - 服务器架构。你需要分别启动服务端（网关）和安装客户端 CLI（用于管理注册）。

1. 启动 MCPJungle 服务端 (推荐使用 Docker)

这是最快启动网关的方式，会自动配置数据库。

# 下载 docker-compose 配置文件
curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.yaml

# 启动服务 (后台运行)
docker compose up -d

启动后，可以通过以下命令验证服务是否正常运行：

curl http://localhost:8080/health

提示: 如果你需要注册基于 stdio 的本地 MCP 服务器（如依赖 npx 或 uvx 的工具），请使用 latest-stdio 标签镜像： MCPJUNGLE_IMAGE_TAG=latest-stdio docker compose up -d

2. 安装 MCPJungle 客户端 CLI

CLI 工具用于向网关注册新的 MCP 服务器。

macOS (推荐):

brew install mcpjungle/mcpjungle/mcpjungle

其他方式: 您可以直接从 GitHub Releases 页面下载对应平台的二进制文件。

验证安装：

mcpjungle version

基本使用

以下流程将演示如何注册一个远程 MCP 服务器，并配置 Claude 通过 MCPJungle 调用其工具。

第一步：注册 MCP 服务器

假设我们要注册一个名为 context7 的远程文档查询服务。使用 CLI 将其添加到网关中：

mcpjungle register --name context7 --url https://mcp.context7.com/mcp

注册成功后，MCPJungle 会自动获取该服务器提供的工具列表。你可以使用以下命令查看已注册的工具：

mcpjungle list tools

第二步：配置 AI 客户端 (以 Claude Desktop 为例)

现在，你只需要让 AI 客户端连接到 MCPJungle 这一个端点，即可访问所有已注册的工具。

打开 Claude Desktop 的配置文件 (claude_desktop_config.json)，添加以下配置：

{
  "mcpServers": {
    "mcpjungle": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp",
        "--allow-http"
      ]
    }
  }
}

注意：如果你的 MCPJungle 部署在远程服务器，请将 localhost 替换为相应的 IP 地址。

第三步：测试调用

重启 Claude Desktop，然后在对话框中输入以下指令进行测试：

Use context7 to get the documentation for `/lodash/lodash`

Claude 将通过 MCPJungle 网关调用 context7__get-library-docs 工具，并返回 Lodash 库的文档。

---

核心概念提示： 在 MCPJungle 中调用工具时，必须使用规范名称格式：<服务器名称>__<工具名称>（例如：context7__get-library-docs）。这是区分不同服务器下同名工具的关键。