Juhe MCP Server

🚀 MCP-Proxy Usage Guide

This guide provides a comprehensive overview of how to install, configure, and use the MCP-Proxy tool. It covers various installation methods, command-line parameters, and testing procedures.

🚀 Quick Start

Get started with MCP-Proxy by following these installation steps.

📦 Installation

Install using the uv tool

Use the following command to install mcp-proxy:

uv tool install mcp-proxy

Run via Docker container

Starting from version 0.3.2, running via Docker container is supported:

Pull the image and start the container:

docker run -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --help

Extend the container image

If you need to extend the image to include other executables, you can create a custom Dockerfile:

Example Dockerfile:

# file: mcp-proxy.Dockerfile

FROM ghcr.io/sparfenyuk/mcp-proxy:latest

# Install the 'uv' package
RUN python3 -m ensurepip && pip install --no-cache-dir uv

ENV PATH="/usr/local/bin:$PATH" \
    UV_PYTHON_PREFERENCE=only-system

ENTRYPOINT [ "mcp-proxy" ]

Docker Compose configuration

Define the service using a custom Dockerfile:

Example docker-compose.yaml:

services:
  mcp-proxy-custom:
    build:
      context: .
      dockerfile: mcp-proxy.Dockerfile
    network_mode: host
    restart: unless-stopped
    ports:
      - 8096:8096
    command: "--pass-environment --sse-port=8096 --sse-host 0.0.0.0 uvx mcp-server-fetch"

⚠️ Important Note

Don't forget to set the --pass-environment parameter; otherwise, you'll encounter the error: "Interpreter not found in the managed installation or search path."

💻 Usage Examples

Basic Usage

usage: mcp-proxy [-h] [-H KEY VALUE] [-e KEY VALUE] [--pass-environment | --no-pass-environment] [--sse-port SSE_PORT] [--sse-host SSE_HOST]
                 [--allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]]
                 [command_or_url] [args ...]

Start the MCP proxy, supporting two modes: as an SSE or stdio client.

Positional arguments:
  command_or_url        The command or URL to connect to. When it's a URL, an SSE client will be run; otherwise, the given command will be run and connected as a stdio client. See relevant options for details.

Options:
  -h, --help            Show this help message and exit

SSE client options:
  -H KEY VALUE, --headers KEY VALUE
                        Pass headers to the SSE server. Can be used multiple times.
  
stdio client options:
  args                  Any additional arguments for the given command
  -e KEY VALUE, --env KEY VALUE
                        Environment variables to use when spawning the server. Can be used multiple times.
  --pass-environment, --no-pass-environment
                        Pass all environment variables when spawning the server.

SSE server options:
  --sse-port SSE_PORT   The exposed SSE server port. Default is a random port
  --sse-host SSE_HOST   The exposed SSE server host. Default is 127.0.0.1
  --allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]
                        Allowed SSE server origins. Can be used multiple times. CORS is not allowed by default.

Examples:
  mcp-proxy http://localhost:8080/sse
  mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
  mcp-proxy -e DEBUG=true my_command.sh

Testing Methods

Verify the installation

Check if the installation was successful:

uv tool list | grep mcp-proxy

Update the tool

Update to the latest version:

uv tool update mcp-proxy

Uninstall the tool

Uninstall the installed tool:

uv tool remove mcp-proxy

📚 Documentation

• If you need more information, please refer to the original English documentation or visit the project homepage.
• If you encounter issues during use, you can consult relevant technical materials or contact the maintainers for help.