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.