项目介绍
MCP Funnel
一个Model Context Protocol (MCP)代理服务器，可以将多个MCP服务器聚合到一个接口中，使您可以通过Claude Desktop或Claude Code CLI同时使用来自多个来源的工具。
🎯 目的
大多数MCP服务器暴露所有工具而没有过滤选项，这会消耗宝贵的上下文空间。
MCP Funnel使您可以：
- 同时连接多个MCP服务器（如GitHub、内存、文件系统等）
- 细粒度工具过滤：隐藏不需要的特定工具
- 基于模式的过滤：使用通配符来隐藏整个类别的工具
- 减少上下文使用：通过仅暴露必要的工具显著减少令牌消耗
🏗️ 架构
┌────────────────────────┐
│ CLI（例如Claude Code） │
└──────┬─────────────────┘
│ MCP协议通过stdio
┌──────▼──────┐
│ MCP Funnel │ ← 过滤和动态发现发生在这里
└──────┬──────┘
│
┌───┴──────┬─────────┬─────────┐
│ │ │ │
┌──▼────┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐
│GitHub │ │Memory │ │FS │ │ ... │ ← 每个都暴露所有工具
└───────┘ └───────┘ └───────┘ └───────┘
MCP Funnel：
- 作为客户端连接到多个MCP服务器
- 接收每个服务器的所有工具
- 应用您的过滤规则
- 只向客户端暴露经过过滤的工具
- 将工具调用路由到适当的后端服务器
🚀 功能
- 多服务器聚合：连接任意数量的MCP服务器
- 工具命名空间：自动前缀防止命名冲突（如
github__create_issue，memory__store_memory） - 灵活过滤：使用通配符模式显示/隐藏工具
- 精细控制：过滤服务器不允许禁用的个别工具
- 上下文优化：通过选择性过滤减少MCP工具上下文使用量40%-60%
- 自定义传输：支持基于stdio的MCP服务器（Docker、NPX、本地二进制文件）
- 服务器日志前缀：清晰标识哪个服务器在记录什么
- 动态工具发现：实验功能以减少初始上下文使用（见限制）
- 核心工具模式：超最小上下文模式，仅暴露选定的MCP Funnel工具并进行动态桥接（上下文减少95%以上）
💡 为什么使用MCP Funnel？
上下文问题
典型的MCP设置可能暴露：
- GitHub MCP：约70个工具
- 内存MCP：约30个工具
- 文件系统MCP：约15个工具
- 总计：超过115个工具，消耗40k令牌
其中许多工具很少被使用：
- 工作流管理工具
- 团队/组织工具
- 调试和诊断工具
- 仪表板界面
- 高级嵌入操作
或者与聊天对话：
之前
<details> <summary>对于这个`.mcp.json`配置</summary> {<br/> "mcpServers": {<br/> "memory": {<br/> "command": "uv",<br/> "args": ["--directory", "/Users/me/_mcp/mcp-memory-service", "run", "memory", "server"]<br/> },<br/> "context7": {<br/> "command": "npx",<br/> "args": ["-y", "@upstash/context7-mcp", "--api-key", "API_KEY"]<br/> },<br/> "code-reasoning": {<br/> "command": "npx",<br/> "args": ["-y", "@mettamatt/code-reasoning"]<br/> },<br/> "filesystem": {<br/> "command": "npx",<br/> "args": [<br/> "-y",<br/> "@modelcontextprotocol/server-filesystem",<br/> "allowed/file/path"<br/> ]<br/> },<br/> "github": {<br/> "command": "docker",<br/> "args": [<br/> "run",<br/> "-i",<br/> "--rm",<br/> & "ghcr.io/github/github-mcp-server"<br/> ],<br/> "secretProviders": [<br/> { "type": "dotenv", "config": { "path": ".env" } }<br/> ]<br/> }<br/> }<br/> }<br/> ``` </details>> /context
⎿ ⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ 上下文使用
⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ claude-opus-4-1-20250805 • 42k/200k令牌 (21%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ MCP工具：25.4k令牌 (12.7%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ 消息：96令牌 (0.0%)
之后
> /context
⎿ ⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛀ 上下文使用
⛀ ⛀ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ claude-opus-4-1-20250805 • 18k/200k令牌 (9%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ MCP工具：2.4k令牌 (1.2%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛁ 消息：96令牌 (0.0%)
然后使用它：
> 发现代码推理工具
⏺ 我将帮助您发现代码推理工具。
McCartney mcp-funnel - discover_tools_by_words (MCP)(words: "reasoning", enable: false)
⎿ 找到了1个工具：
○ code-reasoning__code-reasoning: 🧠 一种详细的工具，通过顺序思维进行动态和反思的问题解决。
… +29行（按ctrl+o展开）
McCartney 找到了！code-reasoning__code-reasoning工具可用于详细代码分析和推理。让我启用它：
McCartney mcp-funnel - load_toolset (MCP)(tools: ["code-reasoning__code-reasoning"])
⎿ 加载了匹配指定模式的1个工具
McCartney 现在启用了代码推理工具。它提供：
- 通过顺序思维进行动态问题解决
- 分支和探索替代方案的能力
- 修正早期思考的修订能力
- 随着理解加深而适应的灵活思维进程
您现在可以使用此工具进行代码逻辑分析、理解复杂实现以及逐步解决编程挑战。
🔧 安装
安装自定义命令
MCP Funnel支持从npm包动态安装额外命令。您可以全局安装命令到用户目录（~/.mcp-funnel/packages），这样它们将在所有项目中可用。
使用manage_commands工具
manage_commands是内置的MCP Funnel工具，用于安装、更新和移除命令包，无需单独的CLI包装器。只要未设置exposeCoreTools（或显式包含manage_commands），该工具默认暴露。
通过bridge_tool_request（Claude、Codex CLI等）请求示例安装：
{
"name": "manage_commands",
"arguments": {
"action": "install",
"package": "@awesome-org/mcp-command",
"version": "1.2.3"
}
}
支持的有效负载字段：
action：install、update或uninstall（必需）。package：npm包规范或已安装命令名称（必需）。version：可选版本（仅限安装）——例如，"1.2.3"。force：即使已存在也重新安装的布尔标志（仅限安装）。removeData：卸载时删除缓存数据的布尔标志（仅限卸载）。
响应包括有关命令的结构化细节、任何发现的工具以及热重载是否成功的信息。当在MCP客户端内部运行时，可以直接调用该工具；无需额外的CLI管道。
命令发现
用户安装的命令会自动从~/.mcp-funnel/packages/node_modules/发现并加载，与内置命令一起。它们尊重您的配置：
- 如果指定了
commands.list，则只加载白名单中的命令 - 使用
hideTools模式隐藏命令 - 命令中的工具由
exposeTools模式过滤
⚙️ 配置
MCP Funnel支持两种方式指定配置：
-
隐式（默认）：查找当前工作目录下的
.mcp-funnel.jsonnpx mcp-funnel # 使用./.mcp-funnel.json -
显式：指定自定义配置文件路径
npx mcp-funnel /path/to/config.json -
用户基础配置（自动合并）
如果存在，
~/.mcp-funnel/.mcp-funnel.json将与项目配置合并。项目值覆盖用户基础值。数组替换（不进行串联）。
在项目目录中创建一个.mcp-funnel.json文件：
{
"servers": {
"github": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"],
"secretProviders": [{ "type": "dotenv", "config": { "path": ".env" } }]
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
},
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/directory"
]
}
},
"hideTools": [
"github__list_workflow_runs",
"github__get_workflow_run_logs",
"memory__debug_*",
"memory__dashboard_*",
"github__get_team_members"
]
}
传递密钥/环境变量示例：GitHub MCP
配置GitHub MCP时处理安全令牌非常简单：
.mcp-funnel.json:
{
"servers": {
"github": {
"transport": {
"type": "streamable-http",
"url": "https://api.githubcopilot.com/mcp/"
},
"auth": {
"type": "bearer",
"token": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
},
"secretProviders": [
{ "type": "dotenv", "config": { "path": ".env" } }
]
}
}
}
.env:
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_github_token_here
就这样！secretProviders会自动从.env加载您的令牌，确保其安全且不在配置文件中。
配置选项
- servers：要连接的MCP服务器记录（服务器名称作为键）
- 键：服务器名称（用作工具前缀）
command：要执行的命令args：命令参数（可选）env：环境变量（可选，已弃用 - 使用secretProviders代替）secretProviders：用于安全环境变量管理的密钥提供者配置数组（推荐）
- defaultSecretProviders：应用于所有服务器的默认密钥提供者（可选）
- defaultPassthroughEnv：默认情况下传递给所有服务器的环境变量（可选）
- alwaysVisibleTools：始终暴露的工具模式，绕过发现模式（可选）
- exposeTools：外部工具的包含模式（可选）
- hideTools：外部工具的排除模式（可选）
- exposeCoreTools：内部MCP Funnel工具的包含模式（可选，默认启用所有）
alwaysVisibleTools vs exposeTools
- 当您希望工具在启动时可见时，仅使用exposeTools。对于服务器支持的工具，不需要在alwaysVisibleTools中重复。
- 当您希望服务器工具绕过所有门控（暴露/隐藏，未来的模式更改）时，使用alwaysVisibleTools。它胜过hideTools。您不需要在exposeTools中重复它。
- 命令：命令工具使用其工具名（如
npm_lookup，ts-validate）或通配符（如npm_*）在exposeTools/hideTools模式中直接暴露。
过滤模式
模式匹配前缀的工具名（serverName__toolName），支持通配符（*）：
单个工具：
github__get_team_members- 隐藏GitHub服务器上的特定工具memory__check_database_health- 隐藏内存服务器上的特定工具
通配符模式：
memory__dashboard_*- 内存服务器上的所有仪表盘工具github__debug_*- GitHub服务器上的所有调试工具*__workflow_*- 任何服务器上的所有工作流相关工具memory__ingest_*- 内存服务器上的所有摄入工具*__list_*- 任何服务器上的所有列表工具
常见过滤示例：
"hideTools": [
"memory__dashboard_*", // 隐藏内存服务器上的所有仪表盘工具
"memory__debug_*", // 隐藏内存服务器上的所有调试工具
"memory__ingest_*", // 隐藏内存服务器上的摄入工具
"github__get_team_members", // 隐藏特定的GitHub工具
"github__*_workflow_*", // 隐藏GitHub的工作流工具
"*__list_*_artifacts" // 隐藏所有服务器上的工件列表工具
]
注意：始终使用服务器前缀（如github__，memory__）来针对特定服务器的工具。使用*__开头来匹配任何服务器的工具。
核心工具过滤
MCP Funnel包括用于发现和桥接的内部工具。使用exposeCoreTools控制哪些核心工具被暴露：
"exposeCoreTools": ["discover_*", "load_toolset"] // 仅暴露发现工具和工具集加载
可用的核心工具：
discover_tools_by_words- 按关键词搜索工具get_tool_schema- 获取工具的输入模式bridge_tool_request- 动态执行工具load_toolset- 加载预定义的工具模式
如果未指定exposeCoreTools，默认启用所有核心工具。
🚀 使用
与Claude Code CLI
添加到您的配置（例如path/to/your/project/.mcp.json）：
{
"mcpServers": {
"mcp-funnel": {
"command": "npx",
"args": ["-y", "mcp-funnel"]
}
}
}
这将使用当前工作目录下的.mcp-funnel.json。要使用自定义配置路径：
{
"mcpServers":