MCP-Compose-Proxy-Shim

What is MCP-Compose-Proxy-Shim?

MCP-Compose-Proxy-Shim is a bridge that connects local LLM clients (such as Claude Desktop) to remote MCP-Compose servers running in Docker containers. It intercepts local MCP server calls and redirects them to a remote MCP-Compose proxy, acting as a transparent bridge.

How to use MCP-Compose-Proxy-Shim?

Clone the repository, run npm install, and make scripts executable with chmod +x bin/npx lib/mcp-shim.js. Ensure MCP-Compose is running (mcp-compose up and mcp-compose proxy). Edit Claude Desktop’s configuration file (claude_desktop_config.json) to point to the bin/npx script with your desired MCP server arguments. Set environment variables such as MCP_PROXY_URL (default http://localhost:9876) and MCP_API_KEY before launching Claude Desktop, then restart the client.

Key features of MCP-Compose-Proxy-Shim

• Use Claude Desktop with MCP servers running in Docker containers
• Avoid limitations and costs of paid remote MCP servers
• Leverage all power and flexibility of Docker-based MCP servers
• Works with filesystem, memory, weather and other MCP servers
• Includes security features: path sanitization, rate limiting, API key authentication
• Supports response caching, retry logic, and configurable logging

Use cases of MCP-Compose-Proxy-Shim

• Run containerized filesystem, memory, or weather MCP servers with Claude Desktop
• Use local LLM clients with Docker-based MCP servers without requiring a Claude Max plan
• Combine multiple containerized MCP servers behind a single proxy for a local client
• Securely expose remote MCP servers to desktop clients with authentication and rate limiting

FAQ from MCP-Compose-Proxy-Shim

What are the system requirements?

Node.js v14 or later, Claude Desktop or another MCP-compatible LLM client, and a running MCP-Compose instance with its proxy.

How does the shim communicate with MCP-Compose?

The shim talks to Claude via stdin/stdout as expected, then forwards all requests to the MCP-Compose proxy behind the scenes. Results flow back through the proxy to the shim and then to Claude.

What environment variables can I configure?

Key variables include MCP_PROXY_URL (proxy address), MCP_API_KEY, MCP_DEBUG, MCP_LOG_LEVEL, MCP_CACHE, MCP_CACHE_TTL_MS, MCP_MAX_RETRIES, and MCP_LOG_FILE. Defaults are documented in the README.

Where are logs written?

Logs go to stderr when MCP_DEBUG=true, or to a file at /tmp/mcp-shim-[server].log when MCP_LOG_FILE=true.

What security features are included?

Path sanitization to prevent directory traversal, rate limiting to prevent abuse, request size limiting, API key authentication, and secure error handling.