Mcpjungle

🚀 🌳 MCPJungle 🌳

MCPJungle 是一个专为私有 AI 代理设计的自托管 MCP 网关，它作为组织内所有 模型上下文协议 服务器的单一事实来源注册表，为开发者和 MCP 客户端提供了便捷的管理和使用方式。

🚀 快速开始

本快速入门指南将引导你完成以下操作：

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 或从 发布页面 下载客户端二进制文件。

brew install mcpjungle/mcpjungle/mcpjungle

将 context7 远程 MCP 服务器添加到 MCPJungle：

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

尝试向 Claude 提出以下请求：

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

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

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

✨ 主要特性

• 集中管理：开发者可以从一个中央位置注册和管理 MCP 服务器及其提供的工具。
• 便捷发现：MCP 客户端可以从单个“网关”MCP 服务器发现和使用所有工具。
• 安全访问：为生产级 AI 代理提供内置的安全、隐私和访问控制机制。
• 工具分组：允许将可用工具的子集暴露给 MCP 客户端，以提高性能。
• 可观测性：支持 Prometheus 兼容的 OpenTelemetry 指标，便于监控。

📦 安装指南

⚠️ 重要提示

MCPJungle 目前处于 测试版 阶段。 我们正在积极努力使其达到生产级可靠性。你可以通过 发起讨论 提供反馈。

MCPJungle 以独立二进制文件的形式分发。你可以从 发布页面 下载，也可以使用 Homebrew 进行安装：

brew install mcpjungle/mcpjungle/mcpjungle

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

mcpjungle version

⚠️ 重要提示

在 macOS 上，你必须使用 Homebrew 进行安装，因为编译后的二进制文件尚未进行 公证。

MCPJungle 提供了一个 Docker 镜像，适用于运行注册表服务器：

docker pull mcpjungle/mcpjungle

💻 使用示例

服务器端

MCPJungle 服务器负责管理所有注册的 MCP 服务器，并为 AI 代理提供统一的 MCP 网关，以便发现和调用这些服务器提供的工具。网关通过可流式传输的 HTTP 传输运行，可通过 /mcp 端点访问。

在 Docker 中运行

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

# docker-compose.yaml 针对个人在本地机器上使用进行了优化。
# mcpjungle 默认以 `development` 模式运行。
curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.yaml
docker compose up -d

# docker-compose.prod.yaml 针对组织在远程服务器上为多个用户部署进行了优化。
# mcpjungle 默认以 `production` 模式运行，该模式启用了企业级功能。
curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.prod.yaml
docker compose -f docker-compose.prod.yaml up -d

这将启动 MCPJungle 服务器以及一个持久的 Postgres 数据库容器。你可以通过以下命令快速验证服务器是否正在运行：

curl http://localhost:8080/health

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

MCPJUNGLE_IMAGE_TAG=latest-stdio docker compose up -d

💡 使用建议

如果你使用的是 docker-compose.yaml，这已经是默认的镜像标签。只有在使用 docker-compose.prod.yaml 时，才需要指定 stdio 镜像标签。

这个镜像体积较大，但在依赖基于 stdio 的 MCP 服务器时，本地运行非常方便。例如，如果你只需要注册像 context7 和 deepwiki 这样的远程 MCP 服务器，可以使用标准（最小）镜像；但如果你还想使用像 filesystem、time、github 等基于 stdio 的服务器，则应使用 stdio 标签的镜像。

⚠️ 重要提示

如果你的 stdio 服务器依赖于 npx 或 uvx 以外的工具，你需要创建一个包含这些依赖项和 mcpjungle 二进制文件的自定义 Docker 镜像。

生产部署

默认的 MCPJungle Docker 镜像 非常轻量级，只包含一个最小的基础镜像和 mcpjungle 二进制文件，因此适合并推荐用于生产部署。对于数据库，建议部署一个单独的 Postgres 数据库集群，并将其端点提供给 mcpjungle（见下面的 数据库 部分）。你可以查看 标准 Docker 镜像 和 stdio Docker 镜像 的定义。

直接在主机上运行

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

mcpjungle start

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

数据库

mcpjungle 服务器依赖于数据库，默认情况下，它会在当前工作目录中创建一个 SQLite 数据库。这在本地测试时是可以的。你也可以为服务器提供一个 Postgresql 数据库的 DSN：

export DATABASE_URL=postgres://admin:root@localhost:5432/mcpjungle_db

# 作为容器运行
docker run mcpjungle/mcpjungle:latest

# 或者直接运行
mcpjungle start

客户端

服务器启动后，你可以使用 mcpjungle CLI 与其进行交互。MCPJungle 目前支持使用 stdio 和 可流式传输的 HTTP 传输的 MCP 服务器。

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

假设你已经在本地 http://127.0.0.1:8000/mcp 运行了一个可流式传输的 HTTP MCP 服务器，它提供了像 add、subtract 等基本数学工具。你可以使用以下命令将这个 MCP 服务器注册到 MCPJungle：

mcpjungle register --name calculator --description "Provides some basic math tools" --url http://127.0.0.1:8000/mcp

如果你使用 docker compose 运行服务器，并且不在 Linux 上，你需要使用 host.docker.internal 代替本地回环地址：

mcpjungle register --name calculator --description "Provides some basic math tools" --url http://host.docker.internal:8000/mcp

注册表现在将开始跟踪这个 MCP 服务器并加载其工具。你也可以提供一个配置文件来注册 MCP 服务器：

cat ./calculator.json
{
  "name": "calculator",
  "transport": "streamable_http",
  "description": "Provides some basic math tools",
  "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}'

⚠️ 重要提示

在 MCPJungle 中，工具必须通过其规范名称引用，规范名称遵循 <mcp-server-name>__<tool-name> 的模式。服务器名称和工具名称用双下划线 __ 分隔。例如，如果你注册了一个提供 git_commit 工具的 MCP 服务器 github，你可以在 MCPJungle 中使用 github__git_commit 名称调用它。你的 MCP 客户端也必须使用这个规范名称通过 MCPJungle 调用工具。

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

{
  "name": "<name of your mcp server>",
  "transport": "streamable_http",
  "description": "<description>",
  "url": "<url of the mcp server>",
  "bearer_token": "<optional bearer token for authentication>"
}

注册基于 STDIO 的服务器

以下是一个使用 STDIO 传输的 MCP 服务器的示例配置文件（假设为 filesystem.json）：

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

你可以通过提供配置文件将这个 MCP 服务器注册到 MCPJungle：

mcpjungle register -c ./filesystem.json

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

{
  "name": "<name of your mcp server>",
  "transport": "stdio",
  "description": "<description>",
  "command": "<command to run the mcp server, eg- 'npx', 'uvx'>",
  "args": ["arguments", "to", "pass", "to", "the", "command"],
  "env": {
    "KEY": "value"
  }
}

你可以观看一个关于 如何注册基于 STDIO 的 MCP 服务器 的快速视频。

💡 使用建议

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

限制 🚧

MCPJungle 在调用工具时会创建新连接。对于 STDIO 服务器，每次调用工具都会启动一个新的子进程。这会带来一些性能开销，但确保了没有内存泄漏。这也意味着目前 MCPJungle 不支持与 MCP 服务器的有状态连接。我们希望听取你的反馈以改进这个机制，欢迎 发起讨论 或 提交问题。

注销 MCP 服务器

你可以从 mcpjungle 中移除 MCP 服务器：

mcpjungle deregister calculator
mcpjungle deregister filesystem

移除后，这个 MCP 服务器及其工具将不再对你或你的 MCP 客户端可用。

与其他 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 的快速视频。

启用/禁用工具

你可以启用或禁用特定工具或 MCP 服务器提供的所有工具。如果工具被禁用，它将无法通过 MCPJungle 代理访问，因此任何 MCP 客户端都无法查看或调用它。

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

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

# 禁用 `context7` MCP 服务器提供的所有工具
mcpjungle disable context7

# 重新启用 `context7` 的所有工具
mcpjungle enable context7

被禁用的工具仍然可以通过 mcpjungle 的 HTTP API 访问，因此你仍然可以从 CLI（或任何其他 HTTP 客户端）管理它。

⚠️ 重要提示

当新服务器在 MCPJungle 中注册时，其所有工具默认 启用。

工具组

随着你向 MCPJungle 添加更多 MCP 服务器，通过网关可用的工具数量可能会显著增加。如果你的 MCP 客户端通过网关 MCP 暴露于数百个工具，其性能可能会下降。MCPJungle 允许你使用 工具组 仅向 MCP 客户端暴露所有可用工具的子集。

你可以创建一个新组，并仅包含你希望暴露的特定工具。组创建后，mcpjungle 会为其返回一个唯一的端点。然后，你可以配置 MCP 客户端使用这个特定于组的端点，而不是主网关端点。

创建工具组

你可以通过向 create group 命令提供 JSON 配置文件来创建新的工具组。你必须为组指定一个唯一的 name 和一个你希望通过其 MCP 代理暴露的 included_tools 列表。

以下是一个工具组配置文件（claude-tools-group.json）的示例：

{
  "name": "claude-tools",
  "description": "This group only contains tools for Claude Desktop to use",
  "included_tools": [
    "filesystem__read_file",
    "deepwiki__read_wiki_contents",
    "time__get_current_time"
  ]
}

这个组不是暴露所有 MCP 服务器中的 20 个工具，而是只暴露 3 个精选工具。你可以在 mcpjungle 中创建这个组：

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

Tool Group claude-tools created successfully
It is now accessible at the following streamable http endpoint:

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

然后，你可以配置 Claude（或任何其他 MCP 客户端）使用这个特定于组的端点来访问 MCP 服务器。客户端将只能看到并使用这 3 个工具，而不会知道 MCPJungle 中注册的任何其他工具。

💡 使用建议

你可以运行 mcpjungle list tools 查看所有可用工具，并选择你希望包含在组中的工具。

你也可以观看一个关于 使用工具组 的视频。

管理工具组

你目前可以执行列出所有组、查看特定组的详细信息和删除组等操作。

# 列出所有工具组
mcpjungle list groups

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

# 删除组
mcpjungle delete group claude-tools

⚠️ 重要提示

如果一个工具包含在组中，但后来被全局禁用或删除，那么它将无法通过组的 MCP 端点访问。但如果该工具后来重新启用或添加，它将自动在组中再次可用。

限制 🚧

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

身份验证

MCPJungle 目前支持身份验证，如果你的可流式传输 HTTP MCP 服务器接受静态令牌进行身份验证。这在使用像 HuggingFace、Stripe 等 SaaS 提供的 MCP 服务器时很有用，这些服务器需要你的 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>"
}

OAuth 流程支持即将推出！

企业功能 🔒

如果你在组织中运行 MCPJungle，建议以 production 模式运行服务器：

# 通过以生产模式运行启用企业功能
mcpjungle start --prod

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

# 或者使用上述的生产 docker compose 文件
docker compose -f docker-compose.prod.yaml up -d

默认情况下，mcpjungle 服务器以 development 模式运行，这对于个人在本地运行非常理想。在生产模式下，服务器实施更严格的安全策略，并提供额外的功能，如身份验证、访问控制列表（ACLs）、可观测性等。

在以生产模式启动服务器后，你必须在客户端机器上运行以下命令对其进行初始化：

mcpjungle init-server

这将在服务器中创建一个管理员用户，并将其 API 访问令牌存储在你的主目录（~/.mcpjungle.conf）中。然后，你可以使用 mcpjungle CLI 向服务器发出经过身份验证的请求。

访问控制

在 development 模式下，所有 MCP 客户端都可以完全访问 MCPJungle 代理中注册的所有 MCP 服务器。production 模式允许你控制哪些 MCP 客户端可以访问哪些 MCP 服务器。

假设你在生产模式下的 MCPJungle 中注册了 2 个 MCP 服务器 calculator 和 github。默认情况下，没有 MCP 客户端可以访问这些服务器。你必须在 mcpjungle 中创建一个 MCP 客户端，并明确允许它访问 MCP 服务器。

# 为你的 Cursor IDE 创建一个新的 MCP 客户端，它可以访问 calculator 和 github MCP 服务器
mcpjungle create mcp-client cursor-local --allow "calculator, github"

MCP client 'cursor-local' created successfully!
Servers accessible: calculator,github

Access token: 1YHf2LwE1LXtp5lW_vM-gmdYHlPHdqwnILitBhXE4Aw
Send this token in the `Authorization: Bearer {token}` HTTP header.

Mcpjungle 为你的客户端创建一个访问令牌。配置你的客户端或代理在向 mcpjungle 代理发出请求时，在 Authorization 头中发送此令牌。例如，你可以在 Cursor 中添加以下配置以连接到 MCPJungle：

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

通过这种方式可以访问特定服务器的客户端可以查看和调用该服务器提供的所有工具。

⚠️ 重要提示

如果你不指定 --allow 标志，MCP 客户端将无法访问任何 MCP 服务器。

OpenTelemetry

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

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

# 启用 OpenTelemetry 指标
export OTEL_ENABLED=true

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

# 启动服务器
mcpjungle start

mcpjungle 服务器启动后，指标可在 /metrics 端点访问。

🔧 技术细节

• 连接管理：MCPJungle 目前不维护与注册的 MCP 服务器的任何长期连接。对于可流式传输的 HTTP 服务器，每次调用工具时都会创建一个新连接；对于 STDIO 服务器，每次调用工具时都会创建一个新连接并启动一个新的子进程。这虽然会带来一些性能开销，但确保了没有内存泄漏。
• 身份验证：目前不支持 OAuth 流程进行身份验证，这是一个正在进行的工作。我们正在收集更多关于人们如何在 MCP 服务器中使用 OAuth 的反馈。

📄 许可证

文档中未提及相关内容，暂不展示。

🔚 当前限制 🚧

我们仍在不断改进，目前存在以下限制：

1. 连接管理：MCPJungle 不会与注册的 MCP 服务器保持任何长期连接。每次调用可流式传输 HTTP 服务器中的工具时，mcpjungle 会创建一个新连接来处理请求；每次调用 STDIO 服务器中的工具时，mcpjungle 会创建一个新连接并启动一个新的子进程来运行该服务器。请求处理完成后，它会终止该子进程。因此，每次调用工具都会启动一个新的 stdio 服务器进程。这会带来一些性能开销，但确保了没有内存泄漏。这也意味着如果你依赖与 MCP 服务器的有状态连接，mcpjungle 目前无法提供该功能。我们计划在未来版本中改进此机制，并欢迎社区提供建议！
2. 身份验证：MCPJungle 目前不支持 OAuth 流程进行身份验证。这是一个正在进行的工作。我们正在收集更多关于人们如何在 MCP 服务器中使用 OAuth 的反馈，欢迎 发起讨论 或 提交问题 分享你的使用案例。

💻 贡献

我们欢迎社区的贡献！

• 贡献指南和标准：请参阅 CONTRIBUTION.md。
• 开发设置和技术细节：请参阅 DEVELOPMENT.md。

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