MCP-Compose-Proxy-Shim

MCP-Compose-Proxy-Shim

A bridge that connects local LLM clients (such as Claude Desktop) to remote MCP-Compose servers running in Docker containers.

🚀 Overview

MCP-Compose-Proxy-Shim allows you to use containerized MCP servers with LLM clients that expect to run MCP servers locally. It acts as a transparent bridge, intercepting local MCP server calls and redirecting them to a remote MCP-Compose proxy.

Key benefits:

• Use Claude Desktop with MCP servers running in Docker containers
• Avoid limitations and costs of paid remote MCP servers
• Leverage all the power and flexibility of Docker-based MCP servers
• Works with filesystem, memory, weather and other MCP servers

This project is designed to integrate with MCP-Compose, a tool for running Model Context Protocol (MCP) servers in Docker containers.

📋 Requirements

• Node.js v14 or later
• Claude Desktop or another MCP-compatible LLM client
• MCP-Compose running with a proxy (see MCP-Compose)

🔧 Installation

1. Clone this repository:

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

2. Install dependencies:

   npm install
   

3. Make scripts executable:

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

🔌 Configuration

Claude Desktop Configuration

Since the "Import Servers" feature requires a Claude Max plan, you need to manually edit Claude's configuration file:

1. Locate Claude Desktop's configuration directory:

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

2. Create or edit the MCP servers configuration file:

   • Create a file called claude_desktop_config.json in the configuration directory
   • Add the following content (adjust paths to your environment):

{
  "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. Important: Restart Claude Desktop after editing the configuration file.

🚀 Usage

Set Up MCP-Compose First

1. First, make sure MCP-Compose is installed and running:

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

   This starts the MCP servers in Docker containers and the proxy on port 9876.

Environment Variables

Before running Claude Desktop, set these environment variables:

Variable	Description	Default
MCP_PROXY_URL	URL of the MCP-Compose proxy	http://localhost:9876
MCP_API_KEY	API key for authentication	""
MCP_DEBUG	Enable debug output	false
MCP_LOG_LEVEL	Log level (trace, debug, info, warn, error)	info
MCP_CACHE	Enable response caching	true
MCP_CACHE_TTL_MS	Cache TTL in milliseconds	300000 (5 min)
MCP_MAX_RETRIES	Maximum retry attempts	3
MCP_LOG_FILE	Enable logging to file	false

🔍 How It Works

1. The bin/npx script intercepts calls to MCP servers that Claude would normally make locally
2. Instead of running the actual server, it starts our lib/mcp-shim.js script
3. The shim communicates with Claude via stdin/stdout as expected
4. Behind the scenes, it forwards all requests to your MCP-Compose proxy
5. The proxy handles the actual communication with Docker containers
6. Results flow back through the proxy to the shim and then to Claude

📝 Logging

Logs are written to:

• Console (stderr) when MCP_DEBUG=true
• File at /tmp/mcp-shim-[server].log when MCP_LOG_FILE=true

🔒 Security Features

• Path sanitization to prevent directory traversal
• Rate limiting to prevent abuse
• Request size limiting
• Authentication via API keys
• Secure error handling

📚 Related Projects

• MCP-Compose: Docker orchestration for MCP servers
• Model Context Protocol: Official MCP documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a pull request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.