MCP-Compose-Proxy-Shim

MCP-Compose-Proxy-Shim

用于连接本地大模型客户端（例如 Claude Desktop）与运行在 Docker 容器中的远程 MCP-Compose 服务的桥接工具。

🚀 概述

MCP-Compose-Proxy-Shim 让你可以在需要 MCP 服务在本地运行的大模型客户端中使用容器化 MCP 服务。它充当透明桥接工具，拦截本地 MCP 服务调用，并将其重定向到远程 MCP-Compose 代理。

主要优势：

• 在 Claude Desktop 中使用运行于 Docker 容器中的 MCP 服务
• 避免付费远程 MCP 服务的限制和费用
• 充分利用基于 Docker 的 MCP 服务的强大功能和灵活性
• 支持文件系统、记忆、天气及其他 MCP 服务

本项目旨在与 MCP-Compose 集成。MCP-Compose 是用于在 Docker 容器中运行 Model Context Protocol（MCP）服务的工具。

📋 要求

• Node.js v14 或更高版本
• Claude Desktop 或其他兼容 MCP 的大模型客户端
• 正在运行且配置了代理的 MCP-Compose（参见 MCP-Compose）

🔧 安装

1. 克隆此仓库：

   git clone https://github.com/phildougherty/mcp-compose-proxy-shim.git
   cd mcp-compose-proxy-shim
   

2. 安装依赖项：

   npm install
   

3. 使脚本可执行：

   chmod +x bin/npx lib/mcp-shim.js
   

🔌 配置

Claude Desktop 配置

由于“导入服务”功能需要 Claude Max 计划，你需要手动编辑 Claude 的配置文件：

1. 找到 Claude Desktop 的配置目录：

   • macOS：~/Library/Application Support/Claude
   • Windows：%APPDATA%\Claude
   • Linux：~/.config/Claude

2. 创建或编辑 MCP 服务配置文件：

   • 在配置目录中创建名为 claude_desktop_config.json 的文件
   • 添加以下内容（根据你的环境调整路径）：

{
  "mcpServers": {
    "filesystem": {
      "command": "/absolute/path/to/mcp-compose-proxy-shim/bin/npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/phildougherty/Documents",
        "/Users/phildougherty/Downloads"
      ]
    },
    "memory": {
      "command": "/absolute/path/to/mcp-compose-proxy-shim/bin/npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

3. 重要提示：编辑配置文件后，重启 Claude Desktop。

🚀 使用方法

请先设置 MCP-Compose

1. 首先，确保已安装并运行 MCP-Compose：

   cd /path/to/mcp-compose
   ./mcp-compose up
   ./mcp-compose proxy
   

   这会在 Docker 容器中启动 MCP 服务，并在端口 9876 上启动代理。

环境变量

启动 Claude Desktop 前，请设置以下环境变量：

变量	描述	默认值
MCP_PROXY_URL	MCP-Compose 代理的 URL	http://localhost:9876
MCP_API_KEY	用于身份验证的 API 密钥	""
MCP_DEBUG	启用调试输出	false
MCP_LOG_LEVEL	日志级别（trace、debug、info、warn、error）	info
MCP_CACHE	启用响应缓存	true
MCP_CACHE_TTL_MS	缓存 TTL（毫秒）	300000（5 分钟）
MCP_MAX_RETRIES	最大重试次数	3
MCP_LOG_FILE	启用写入文件的日志记录	false

🔍 工作原理

1. bin/npx 脚本会拦截 Claude 通常在本地发起的 MCP 服务调用
2. 它不会运行实际服务，而是启动我们的 lib/mcp-shim.js 脚本
3. shim 按预期通过 stdin/stdout 与 Claude 通信
4. 在后台，它会将所有请求转发到你的 MCP-Compose 代理
5. 代理负责与 Docker 容器进行实际通信
6. 结果经由代理返回 shim，再传回 Claude

📝 日志记录

日志写入位置：

• 当 MCP_DEBUG=true 时，写入控制台（stderr）
• 当 MCP_LOG_FILE=true 时，写入 /tmp/mcp-shim-[server].log 文件

🔒 安全功能

• 路径清理，防止目录遍历
• 速率限制，防止滥用
• 请求大小限制
• 通过 API 密钥进行身份验证
• 安全的错误处理

📚 相关项目

• MCP-Compose：用于 MCP 服务的 Docker 编排工具
• Model Context Protocol：MCP 官方文档

🤝 参与贡献

欢迎贡献！欢迎提交拉取请求。

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。