Super MCP (Honestlai)

MCP网关

一个集装箱。一个端口。您的AI编码代理需要的每个MCP。

MCP网关是一个自托管的Docker容器，它将11个最有用的MCP（模型上下文协议）服务器捆绑在一个HTTP端点后面。默认情况下什么都不运行。你选择你需要的东西，翻转一个环境变量，你的AI代理就可以通过干净、可预测的URL即时访问浏览器自动化、文件操作、网络搜索、GitHub、持久内存等。

http://your-server:8080/playwright
http://your-server:8080/filesystem
http://your-server:8080/memory
http://your-server:8080/github
http://your-server:8080/context7
...

没有杂耍端口。无需管理单独的容器。无法确定哪个MCP包支持HTTP，哪个只讲stdio。网关为您处理所有这些。

______________________________________________________________________

为什么存在

如果你花了任何时间使用人工智能编码代理进行构建，你可能也遇到了同样的问题：代理擅长编写代码，但它不能浏览网页，不能触摸文件系统，不能搜索文档，不能查看你的GitHub问题。这些功能中的每一个都存在于自己的MCP服务器中，每个服务器都有自己的设置、自己的传输怪癖和自己的容器或进程来管理。

这个项目最初是为了解决我自己的工作流程中的这个问题。我想坐下来，打开Cursor，让一切都可用——用于测试的浏览器自动化、用于读写代码的文件系统访问、用于跨会话持久的上下文的内存、用于查找内容的web搜索以及用于管理存储库的GitHub集成。我不想运行五个集装箱并记住五个不同的港口号。

结果是一个单一的Docker镜像，在构建时预装了所有11个MCP服务器，但没有启动任何一个。您可以精确控制环境变量中的运行内容 docker-compose.yml内部网关负责将每个服务器桥接到HTTP，并在干净的URL路径上公开它。您的AI代理刚刚连接到 http://your-server:8080/playwright 它奏效了。

______________________________________________________________________

里面是什么

每台服务器都是一个官方或维护良好的社区MCP包，预先安装在映像中并随时可用。你只需决定打开哪些。

SearXNG搜索引擎实例也捆绑在 docker-compose.yml 作为一项独立的服务，因此网络搜索无需额外设置即可开箱即用。

______________________________________________________________________

运作原理

架构很简单。单个Express.js网关监听端口8080，并根据URL路径将传入请求路由到内部MCP后端。

大多数MCP服务器只支持stdio传输（它们从stdin读取并写入stdout）。网关使用 超级通道 使用MCP Streamable HTTP传输将每个节点桥接到HTTP端点。结果是，每个服务器，无论其本机传输方式如何，都可以通过普通HTTP访问。

Your AI Agent
     |
     |  POST http://server:8080/filesystem
     |
     v
 ┌────────────────────────────────────────────────────┐
 │  Docker Container                                  │
 │                                                    │
 │  Express Gateway (:8080)                           │
 │     |                                              │
 │     |  path-based routing                          │
 │     |                                              │
 │     ├── /playwright ──> supergateway (:8081)       │
 │     ├── /filesystem ──> supergateway (:8082)       │
 │     ├── /sequential-thinking ──> supergateway (:8083)│
 │     ├── /memory ──────> supergateway (:8084)       │
 │     ├── /github ──────> supergateway (:8085)       │
 │     ├── /searxng ─────> supergateway (:8086)       │
 │     ├── /context7 ────> supergateway (:8087)       │
 │     ├── /python-interpreter ──> supergateway (:8088)│
 │     ├── /youtube-transcriber ──> supergateway (:8089)│
 │     ├── /fetch ─────────────> supergateway (:8090)│
 │     ├── /git ────────────────> supergateway (:8091)│
 │     └── /video2doc ─────────> supergateway (:8092)│
 │                                                    │
 └────────────────────────────────────────────────────┘

启动时，容器读取您的环境变量，仅启动您启用的服务器，并等待每个后端实际接受连接，然后再启动网关。这可以防止在网关在缓慢启动的MCP服务器之前运行时发生代理错误。然后，后台监视器会监视每个后端，并自动重新启动任何死机的后端，因此单个崩溃的服务器不会使其端点永久损坏。

每个Node.js进程的堆大小上限为256 MB(NODE_OPTIONS=--max-old-space-size=256)以减少许多服务器同时运行时的内存压力。

如果你没有启用任何功能，网关仍然会运行——它只是提供了一个有用的索引页面，告诉你如何打开。

______________________________________________________________________

入门指南

先决条件

• Docker和Docker Compose
• 容器的Docker网络（创建一次： docker network create Network-Bridge)

1.克隆仓库

git clone https://github.com/honestlai/SuperMCP.git
cd SuperMCP

2.选择您的服务器

打开 docker-compose.yml 并取消对所需服务器的注释。例如，要启用Playwright、文件系统和内存：

environment:
  - PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
  - ENABLE_PLAYWRIGHT=true
  - ENABLE_FILESYSTEM=true
  - ENABLE_MEMORY=true

就是这样。当容器启动时，这三台服务器将启动。其他一切都停止了。

3.构建并启动

docker compose up -d --build

第一个构建需要几分钟的时间（安装浏览器、npm包和Python）。后续的启动速度很快。

4.验证它是否正在运行

curl http://localhost:8080/health

你应该得到类似的东西：

{
  "status": "healthy",
  "service": "MCP Gateway",
  "activeMcps": ["playwright", "filesystem", "memory"],
  "endpoints": ["/playwright", "/filesystem", "/memory"]
}

5.将你的AI代理指向它

在Cursor、VS Code或您使用的任何兼容MCP的客户端中，添加服务器：

{
  "mcpServers": {
    "SuperMCP_Playwright": {
      "url": "http://localhost:8080/playwright"
    },
    "SuperMCP_Filesystem": {
      "url": "http://localhost:8080/filesystem"
    },
    "SuperMCP_Memory": {
      "url": "http://localhost:8080/memory"
    }
  }
}

重要提示： 使用独特的名称，如 SuperMCP_Playwright 而不是像这样的通用名称 playwright 或 filesystem。某些MCP客户端（包括Cursor）可能会识别通用名称，并尝试通过stdio在本地运行服务器，而不是连接到远程URL。前缀为 SuperMCP_ 避免这种情况。

替换 localhost 如果您远程连接，请使用服务器的IP地址。做 不 在URL后添加斜线。下面是所有十一台服务器的完整示例 cursor-mcp-config.json.

克劳德桌面（克劳德APP）

Claude Desktop不直接支持远程HTTP MCP服务器；它期望基于stdio的服务器。使用本地网桥（mcp代理或npm适配器），这样Claude就可以与stdio通信，网桥可以与网关通信Streamable HTTP。

配置文件位置： MCP调试指南 建议使用 绝对路径 为了 command，因为Claude可以从任何地方启动，并且工作目录可以是未定义的。

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

您也可以从Claude Desktop打开它： 设置→ 开发者→ 编辑配置.

______________________________________________________________________

选项A：Python 3+pip（无uv/uvx） --适用于任何使用Python 3的系统。

1. 安装桥架一次：

   pip install mcp-proxy
   # or: pip3 install mcp-proxy

1. 找到完整的路径 python3 （在配置中使用这个，这样克劳德即使在最小的PATH中也能找到它）：

   which python3
   # e.g. /opt/homebrew/bin/python3 or /usr/bin/python3

1. 在 claude_desktop_config.json，将该路径用作 command 并将mcp代理作为模块运行：

没有API密钥：

   {
     "mcpServers": {
       "SuperMCP_Memory": {
         "command": "/opt/homebrew/bin/python3",
         "args": [
           "-m", "mcp_proxy",
           "--transport", "streamablehttp",
           "https://your-gateway.example.com/memory"
         ]
       }
     }
   }

带API键 （当 GATEWAY_API_KEY 在网关上设置），添加 env 随着 API_ACCESS_TOKEN （mcp代理将其作为 Authorization: Bearer ):

   {
     "mcpServers": {
       "SuperMCP_Memory": {
         "command": "/opt/homebrew/bin/python3",
         "args": [
           "-m", "mcp_proxy",
           "--transport", "streamablehttp",
           "https://your-gateway.example.com/memory"
         ],
         "env": {
           "API_ACCESS_TOKEN": "your-gateway-api-key-here"
         }
       }
     }
   }

使用您的实际 python3 路径（例如。 /usr/bin/python3 在Linux上）并替换 https://your-gateway.example.com 使用您的SuperMCP基本URL。使用相同的值 API_ACCESS_TOKEN 作为 GATEWAY_API_KEY 在docker compose中。

______________________________________________________________________

选项B:uvx （如果您已经使用 紫外线):

使用 完整路径 到 uvx 这样克劳德就可以繁殖它（例如。 /opt/homebrew/bin/uvx 在macOS上）：

{
  "mcpServers": {
    "SuperMCP_Memory": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["mcp-proxy", "--transport", "streamablehttp", "https://your-gateway.example.com/memory"],
      "env": { "API_ACCESS_TOKEN": "your-gateway-api-key-here" }
    }
  }
}

______________________________________________________________________

选项C:Node.js（npx） --使用env变量作为URL和令牌的替代网桥。

不需要安装；npx按需运行。更喜欢a 完整路径 到 npx （例如。 /opt/homebrew/bin/npx)如果Claude启动服务器时看到“没有这样的文件或目录”。

• 统一资源标识符 （必填）：您的SuperMCP端点URL
• bear_TOKEN （可选）：与您的网关相同 GATEWAY_API_KEY

{
  "mcpServers": {
    "SuperMCP_Memory": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@pyroprompts/mcp-stdio-to-streamable-http-adapter"],
      "env": {
        "URI": "https://your-gateway.example.com/memory",
        "BEARER_TOKEN": "your-gateway-api-key-here"
      }
    }
  }
}

______________________________________________________________________

故障排除： 如果日志显示 Failed to spawn process: No such file or directory，克劳德找不到可执行文件。使用 绝对路径 为了 command （例如。 /opt/homebrew/bin/python3, /usr/bin/python3，或 /opt/homebrew/bin/npx)而不是 python3 或 uvx。请参阅 MCP调试指南 更多。更改配置后，完全退出并重新打开Claude Desktop。

______________________________________________________________________

配置参考

API密钥验证

如果您将网关暴露于网络（尤其是互联网），则应使用API密钥对其进行保护。集 GATEWAY_API_KEY 在你的 docker-compose.yml:

environment:
  - GATEWAY_API_KEY=my-secret-key-here

设置后，对MCP端点的每个请求都必须包含一个承载令牌：

Authorization: Bearer my-secret-key-here

在Cursor/VS Code MCP配置中，添加一个 headers 阻止每个服务器：

{
  "mcpServers": {
    "SuperMCP_Playwright": {
      "url": "http://your-server:8080/playwright",
      "headers": {
        "Authorization": "Bearer my-secret-key-here"
      }
    }
  }
}

没有有效令牌的请求将收到 401 Unauthorized 回应。这 /health 端点保持打开状态，因此Docker健康检查继续工作。如果 GATEWAY_API_KEY 如果未设置，网关将打开运行，不进行身份验证（仅限本地使用）。

• 光标/VS代码： 使用 headers 块与 Authorization: Bearer 如上述示例所示。
• 克劳德桌面： 使用mcp代理并设置 API_ACCESS_TOKEN 在 env 每个服务器的块（请参见 克劳德桌面（克劳德APP）).

启用服务器

每个服务器都由一个环境变量控制。有些服务器需要额外的配置（API密钥、URL）。将这些设置在 environment 你的部分 docker-compose.yml:

如果启用需要API密钥但未提供密钥的服务器，则启动脚本将记录警告并跳过该服务器。没有崩溃。

关于SearXNG的说明： 这 docker-compose.yml 包括一个捆绑的SearXNG实例，该实例具有Valkey缓存作为配套服务。它们会自动与同一Docker网络上的网关一起启动。当您启用SearXNG时，设置 SEARXNG_SERVER_URL=http://searxng:8080 它将连接到捆绑的实例。如果您已经在其他地方运行了自己的SearXNG，请将URL指向那里并删除 searxng 和 valkey 从组合文件中提取服务。

关于上下文7的说明： Context7在没有API键的情况下工作，但具有较低的速率限制。MCP服务器在本地运行，但连接到Context7的托管后端以获取文档数据。您可以在获得免费的API密钥 context7.com 对于更高的速率限制，后端本身是不可自托管的。

Git注意事项： Git MCP需要 /workspace 包含一个初始化的git存储库。如果工作空间卷为空或不包含 .git 目录，Git MCP将无法响应。首先在工作区中克隆或初始化一个仓库，或者如果不需要，跳过启用此服务器。

YouTube转录器配置

YouTube Transcriber通过以下方式从YouTube URL下载音频 yt-dlp 并使用Whisper兼容的语音转文本API进行转录。它适用于任何提供OpenAI兼容的提供商 /audio/transcriptions 终点。

环境变量

如果你设置 TRANSCRIBER_PROVIDER，自动填写基本URL和模型。您仍然可以单独覆盖其中任何一个。如果不设置提供者，则必须显式提供基本URL和模型（或者它们默认为OpenAI）。

遗产 FIREWORKS_API_KEY 变量仍然有效——如果不设置任何变量 TRANSCRIBER_* 变量，它会自动选择Fireworks提供程序。

内置提供程序预设

例子

Groq （提供快速免费套餐）：

- ENABLE_YOUTUBE_TRANSCRIBER=true
- TRANSCRIBER_PROVIDER=groq
- TRANSCRIBER_API_KEY=gsk_your_groq_key_here

开放人工智能:

- ENABLE_YOUTUBE_TRANSCRIBER=true
- TRANSCRIBER_PROVIDER=openai
- TRANSCRIBER_API_KEY=sk-your_openai_key_here

烟花AI:

- ENABLE_YOUTUBE_TRANSCRIBER=true
- TRANSCRIBER_PROVIDER=fireworks
- TRANSCRIBER_API_KEY=fw_your_fireworks_key_here

自定义/自托管端点 （例如，本地Whisper服务器）：

- ENABLE_YOUTUBE_TRANSCRIBER=true
- TRANSCRIBER_API_KEY=any-value
- TRANSCRIBER_BASE_URL=http://my-whisper-server:8000/v1
- TRANSCRIBER_MODEL=whisper-large-v3

Groq具有特定的模型覆盖功能:

- ENABLE_YOUTUBE_TRANSCRIBER=true
- TRANSCRIBER_PROVIDER=groq
- TRANSCRIBER_API_KEY=gsk_your_groq_key_here
- TRANSCRIBER_MODEL=whisper-large-v3

Video2Doc配置

Video2Doc MCP从URL下载视频（或读取本地文件），转录音频，用场景变化检测对关键帧进行采样，用视觉模型分析每一帧，并生成一个包含摘要、动作项和嵌入式屏幕截图的结构化标记文档。

输入： yt-dlp支持的任何URL（Zoom云录制、Loom共享、Google Drive、Vimeo、direct .mp4 链接，500+平台），或下的本地文件路径 /workspace.

输出： 写入的markdown文件 /workspace/outputs/.

每个模型端点都使用标准的OpenAI兼容API-您可以在不更改任何代码的情况下交换提供程序。

配置——统一提供者（推荐）

集 LLM_API_KEY 和 LLM_BASE_URL 所有三个AI任务（视觉、摘要、转录）都会自动使用该提供者。然后只设置每个任务的模型名称，不需要单独的API键。

# One provider for everything
- LLM_API_KEY=your_api_key_here
- LLM_BASE_URL=https://api.fireworks.ai/inference/v1

# Model per task (all on the same provider)
- VISION_MODEL=accounts/fireworks/models/qwen2-vl-72b-instruct
- SUMMARY_MODEL=accounts/fireworks/models/llama4-scout-instruct-basic
- TRANSCRIBER_MODEL=whisper-v3

供应商和模型建议

费用提示： VISION_MODEL 每个采样帧调用一次（最多 max_frames). SUMMARY_MODEL 每个视频调用一次。始终设置 SUMMARY_MODEL 对于快速廉价的文本模型，它大大降低了成本，对摘要的质量没有影响。

转录： 如果您的视力提供者没有Whisper端点（Together AI、Ollama），请设置 TRANSCRIBER_API_KEY 和 TRANSCRIBER_BASE_URL 明确地给Groq或OpenAI。Groq's whisper-large-v3-turbo 是最快、最便宜的选择。

高级：按服务提供商覆盖

如果您希望为不同的任务提供不同的提供者，请设置特定于服务的变量——它们优先于统一的 LLM_* 哪个 ：

示例——Fireworks AI用于视觉，Groq用于转录（最便宜的组合）：

- LLM_API_KEY=fw_your_fireworks_key
- LLM_BASE_URL=https://api.fireworks.ai/inference/v1
- VISION_MODEL=accounts/fireworks/models/qwen2-vl-72b-instruct
- SUMMARY_MODEL=accounts/fireworks/models/llama4-scout-instruct-basic
- TRANSCRIBER_API_KEY=gsk_your_groq_key
- TRANSCRIBER_BASE_URL=https://api.groq.com/openai/v1
- TRANSCRIBER_MODEL=whisper-large-v3-turbo

示例用法（启用后）

# Zoom cloud recording
process_video("https://zoom.us/rec/share/xxxx", "meeting")

# Loom recording
process_video("https://www.loom.com/share/xxxx", "discovery")

# Google Drive video share
process_video("https://drive.google.com/file/d/xxxx/view", "howto")

# Local file (mount it into the workspace volume first)
process_video("/workspace/call-recording.mp4", "meeting")

doc_type 选项： meeting, discovery, howto, general.

私人链接： 如果URL需要登录，请将Netscape格式的Cookie文件装载到容器中并设置 YTDLP_COOKIES_FILE 走自己的路。

______________________________________________________________________

完整配置示例

以下是一切打开时的样子：

environment:
  - PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
  # Core servers
  - ENABLE_PLAYWRIGHT=true
  - ENABLE_FILESYSTEM=true
  - ENABLE_SEQUENTIAL_THINKING=true
  - ENABLE_MEMORY=true
  - ENABLE_PYTHON_INTERPRETER=true
  # GitHub
  - ENABLE_GITHUB=true
  - GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
  # Web search
  - ENABLE_SEARXNG=true
  - SEARXNG_SERVER_URL=http://searxng:8080
  # Documentation lookup
  - ENABLE_CONTEXT7=true
  - CONTEXT7_API_KEY=your_key_here
  # YouTube transcription (pick your provider -- see YouTube Transcriber section above)
  - ENABLE_YOUTUBE_TRANSCRIBER=true
  - TRANSCRIBER_PROVIDER=groq
  - TRANSCRIBER_API_KEY=your_api_key_here
  # Web fetching and local git
  - ENABLE_FETCH=true
  - ENABLE_GIT=true
  # Video2Doc — set LLM_API_KEY + LLM_BASE_URL once, all tasks use that provider
  - ENABLE_VIDEO2DOC=true
  - LLM_API_KEY=your_api_key_here
  - LLM_BASE_URL=https://api.fireworks.ai/inference/v1
  - VISION_MODEL=accounts/fireworks/models/qwen2-vl-72b-instruct
  - SUMMARY_MODEL=accounts/fireworks/models/llama4-scout-instruct-basic
  - TRANSCRIBER_MODEL=whisper-v3

卷

volumes:
  - workspace:/workspace:rw    # Your project files (used by Filesystem MCP)
  - data:/data:rw              # Persistent storage (Memory MCP stores data here)

港口

只有一个端口暴露在外：

ports:
  - "8080:8080"

如果主机上的端口为8080，请更改左侧： "9090:8080" 将使网关在端口9090处可用。

______________________________________________________________________

网关端点

服务器名称与您在上表中看到的完全匹配： playwright, filesystem, sequential-thinking, memory, github, searxng, context7, python-interpreter, youtube-transcriber, fetch, git.

______________________________________________________________________

替代方案：Docker执行模式

每个MCP包都全局安装在容器中，因此您也可以通过以下方式直接连接到它们 docker exec 使用stdio传输。这对于调试很有用，或者如果您的MCP客户端更喜欢stdio而不是HTTP：

docker exec -i SuperMCP npx @playwright/mcp@latest --headless --isolated --no-sandbox --browser chromium
docker exec -i SuperMCP npx @modelcontextprotocol/server-filesystem /workspace
docker exec -i SuperMCP npx @modelcontextprotocol/server-memory
docker exec -i SuperMCP npx @modelcontextprotocol/server-sequential-thinking
docker exec -i SuperMCP npx @modelcontextprotocol/server-github
docker exec -i SuperMCP python3 -m mcp_server_fetch
docker exec -i SuperMCP python3 -m mcp_server_git --repository /workspace

无论通过环境变量启用了哪些服务器，这都是有效的——包总是在那里。

______________________________________________________________________

故障排除

健康检查显示没有服务器处于活动状态 你还没有取消任何评论 ENABLE_* 线条在 docker-compose.yml。取消对所需内容的注释，然后重新启动： docker compose up -d.

特定服务器返回502 后端崩溃或正在重新启动。监视器将在30秒内自动重新启动。检查该服务器的日志以查找潜在错误：

docker exec SuperMCP cat /var/log/mcp/playwright.log
docker exec SuperMCP cat /var/log/mcp/memory.log

GitHub或SearXNG不会启动 这些需要额外的环境变量。确保你已经设置了这两个 ENABLE_* 标志和所需的键/URL。如果缺少所需的变量，容器日志将显示警告：

docker logs SuperMCP | head -30

容器根本无法启动 检查端口8080是否空闲，Docker网络是否存在：

docker network create Network-Bridge    # if it doesn't exist
docker compose down
docker compose build --no-cache
docker compose up -d

一般调试

docker ps | grep SuperMCP                                             # is it running?
docker inspect --format='{{.State.Health.Status}}' SuperMCP           # is it healthy?
docker logs SuperMCP                                                   # what happened on startup?
curl http://localhost:8080/health                                     # what does the gateway say?

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 提交拉取请求

添加新的MCP服务器涉及四个文件： Dockerfile （安装软件包）， start-mcps.sh （添加启动块）， gateway.js （添加到注册表中），以及 docker-compose.yml （添加env变量）。每个服务器的模式都是相同的。

许可证

MIT许可证——有关详细信息，请参阅许可证文件。

致谢

• 模型上下文协议 因为规范使这一切成为可能
• 超级通道 用于将所有内容连接在一起的stdio到HTTP网桥
• 剧作家 用于浏览器自动化
• 用于构建和维护这些服务器包的MCP社区