MCP Controller

MCP控制器

模型上下文协议（MCP）服务器，充当MCP客户端和目标MCP服务器之间的代理，具有 工具过滤 控制哪些工具暴露给客户端的能力。

主要特点

• 🔧 工具筛选：有选择地启用或禁用目标MCP服务器上的特定工具
• 🔍 透明代理：转发所有其他MCP协议消息，无需修改
• ⚡ 零配置：无需更改即可与任何现有的MCP服务器配合使用
• 🛡️ 访问控制：控制客户端可以访问哪些工具以确保安全性和可用性
• 📦 命令行界面：通过命令参数启动任何MCP服务器
• 🔄 优雅地关闭：处理SIGINT/SIGTERM信号以清理进程
• 📝 TypeScript：配备现代ES模块的全型安全

安装

curl -fsSL https://raw.githubusercontent.com/eli0shin/mcp-controller/main/install.sh | bash

或者通过npm安装：

npm install -g mcp-controller

用法

基本代理（无筛选）

# Proxy to a local MCP server
mcp-controller bun run my-server.ts

# Proxy to an npm-distributed MCP server
mcp-controller @modelcontextprotocol/server-sequential-thinking

# Proxy to a Python MCP server
mcp-controller python -m my_mcp_server

# Proxy to any executable MCP server
mcp-controller node server.js --port 3000

工具筛选

控制将目标服务器中的哪些工具暴露给客户端：

# Only allow specific tools (whitelist mode)
mcp-controller --enabled-tools file-read,file-write,search bun run my-server.ts

# Block specific tools (blacklist mode)
mcp-controller --disabled-tools dangerous-tool,admin-commands python -m my_server

# Multiple tools (comma-separated, no spaces around commas)
mcp-controller --enabled-tools tool1,tool2,tool3 node server.js

筛选规则

• --enabled-tools：客户只能使用指定的工具（白名单）
• --disabled-tools：除指定工具外，所有工具都可用（黑名单）
• 互斥：您可以使用其中之一 --enabled-tools 或 --disabled-tools，但不是两者都有
• 区分大小写：工具名称必须与目标服务器中定义的完全匹配
• 没有空格：使用不带空格的逗号分隔值： tool1,tool2,tool3

用例

安全和访问控制

# Production environment - only allow safe read-only tools
mcp-controller --enabled-tools read-file,search,list-files my-server

# Development environment - block dangerous operations
mcp-controller --disabled-tools delete-file,format-disk,restart-system my-server

客户特定定制

# For a documentation client - only text processing tools
mcp-controller --enabled-tools text-search,summarize,translate content-server

# For an admin interface - block user-facing tools
mcp-controller --disabled-tools user-chat,send-email,post-social admin-server

测试与开发

# Test specific functionality by isolating tools
mcp-controller --enabled-tools database-query,cache-get test-server

# Debug by excluding problematic tools
mcp-controller --disabled-tools flaky-api,slow-process debug-server

原理

1. 流程管理：代理接受命令参数并生成目标MCP服务器进程
2. 消息拦截：所有JSON-RPC消息都通过代理双向流动
3. 工具筛选：当客户要求时 tools/list，代理根据您的配置过滤响应
4. 透明转发：所有其他消息（资源、提示、工具调用等）都保持不变
5. 生命周期管理：代理处理进程清理和优雅关闭

建筑

MCP Client ↔ MCP Controller ↔ Target MCP Server
             (Tool Filtering)

消息流

1. 客户→ 控制器→ 目标：透明转发所有请求
2. 目标→ 控制器→ 客户:

- tools/list 根据配置过滤响应 - 所有其他响应均保持不变

什么被过滤

• ✅ tools/list 回应 -根据您的设置过滤工具阵列
• ❌ 工具调用 -单个工具调用通过（过滤后的工具根本不可用）
• ❌ 资源 -资源列表和访问权限保持不变
• ❌ 提示 -提示功能不受影响
• ❌ 其他消息 -初始化、功能等传递

CLI参考

Usage: mcp-controller [--enabled-tools ] [--disabled-tools ]  [args...]

       mcp-controller update

Options:
  --enabled-tools     Comma-separated list of tools to allow (whitelist mode)
  --disabled-tools    Comma-separated list of tools to block (blacklist mode)

Examples:
  mcp-controller bun run server.ts                              # No filtering
  mcp-controller --enabled-tools read,write bun run server.ts   # Only allow read,write
  mcp-controller --disabled-tools delete python -m server       # Block delete tool

错误处理

控制器在启动时验证参数，并将退出并显示有用的错误消息：

# Missing command
$ mcp-controller --enabled-tools read
Error: No target command specified

# Both filtering modes
$ mcp-controller --enabled-tools read --disabled-tools write bun server.ts
Error: --enabled-tools and --disabled-tools are mutually exclusive

# Missing tool list
$ mcp-controller --enabled-tools bun server.ts
Error: --enabled-tools requires a value

发展

# Install dependencies
bun install

# Build release binaries
bun run build

# Run via wrapper against the local release build
./bin/mcp-controller bun run tests/fixtures/mcp-server.ts

# Run in development mode
bun run dev 

# Run tests (includes tool filtering tests)
bun test

# Update installed binary from GitHub Releases
mcp-controller update

# Lint and format
bun run lint
bun run format

# Type check
bun run typecheck

许可证

麻省理工学院