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 社區，與其他貢獻者和維護者交流。