mcp-proxy

mcp-proxy

• mcp-proxy
  • 概要
  • 1. stdio から SSE/StreamableHTTP へ
    • 1.1 設定
    • 1.2 使用例
  • 2. SSE から stdio へ
    • 2.1 設定
    • 2.2 使用例
  • 名前付きサーバー
  • インストール
    • PyPI 経由でインストール
    • Github リポジトリ経由でインストール（最新）
    • コンテナとしてインストール
    • トラブルシューティング
  • コンテナイメージの拡張
  • Docker Compose のセットアップ
  • コマンドライン引数
    • 設定ファイルの例
  • テスト

概要

mcp-proxy は、サーバーのトランスポートを切り替えられるツールです。サポートされているモードは次の 2 つです。

1. stdio から SSE/StreamableHTTP へ
2. SSE から stdio へ

1. stdio から SSE/StreamableHTTP へ

リモート SSE サーバーに接続する stdio プロキシサーバーを実行します。

このモードを使うと、Claude Desktop のようなクライアントは、ネイティブではサポートされていない場合でも、SSE 経由でリモートサーバーと通信できます。

graph LR
    A["Claude Desktop"] <--> |stdio| B["mcp-proxy"]
    B <--> |SSE| C["External MCP Server"]

    style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
    style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px
    style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px

1.1 設定

このモードでは、MCP Server の SSE エンドポイントの URL を、プログラムの最初の引数として指定する必要があります。サーバーが Streamable HTTP トランスポートを使用する場合は、--transport=streamablehttp を渡して mcp-proxy 側でその設定を有効にしてください。

引数

名前	必須	説明	例
command_or_url	はい	接続先の MCP サーバーの SSE エンドポイント	http://example.io/sse
--headers	いいえ	MCP サーバーの SSE 接続で使用するヘッダー	Authorization 'Bearer my-secret-access-token'
--transport	いいえ	MCP サーバーへの接続時に使用するトランスポートプロトコルを指定します。'sse' または 'streamablehttp' を指定できます	streamablehttp
--client-id	いいえ	認証に使用する OAuth2 クライアント ID	your_client_id
--client-secret	いいえ	認証に使用する OAuth2 クライアントシークレット	your_client_secret
--token-url	いいえ	認証に使用する OAuth2 トークンエンドポイント URL	https://auth.example.com/oauth/token
--username	いいえ	認証に使用するユーザー名	user
--password	いいえ	認証に使用するパスワード	password
--digest	いいえ	ダイジェスト認証を使用します

環境変数

名前	必須	説明	例
API_ACCESS_TOKEN	いいえ	--headers Authorization 'Bearer <API_ACCESS_TOKEN>' の代わりに使用できます	YOUR_TOKEN

1.2 使用例

mcp-proxy は MCP クライアントによって起動されることを想定しているため、それに応じて設定する必要があります。

Claude Desktop の場合、設定項目は次のようになります。

{
  "mcpServers": {
    "mcp-proxy": {
      "command": "mcp-proxy",
      "args": [
        "http://example.io/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "access-token"
      }
    }
  }
}

2. SSE から stdio へ

ローカルの stdio サーバーに接続する SSE サーバーを公開するプロキシサーバーを実行します。

これにより、ローカルの stdio サーバーへのリモート接続が可能になります。mcp-proxy は SSE リクエストを受け付けるポートを開き、 MCP リクエストを処理するローカルの stdio サーバーを起動します。

graph LR
    A["LLM Client"] <-->|SSE| B["mcp-proxy"]
    B <-->|stdio| C["Local MCP Server"]

    style A fill:#ffe6f9,stroke:#333,color:black,stroke-width:2px
    style B fill:#e6e6ff,stroke:#333,color:black,stroke-width:2px
    style C fill:#e6ffe6,stroke:#333,color:black,stroke-width:2px

2.1 設定

このモードでは、--sse-port 引数を設定する必要があります。--sse-host 引数を設定すると、SSE サーバーが待ち受けるホスト IP アドレスを指定できます。--env 引数を使用して、ローカルの stdio サーバーに追加の環境変数を渡すことができます。ローカルの stdio サーバーのコマンドライン引数は、区切り文字 -- の後に渡す必要があります。

引数

名前	必須	説明	例
command_or_url	はい	起動する MCP stdio サーバーのコマンド	uvx mcp-server-fetch
--port	いいえ、利用可能なポートをランダムに選択	MCP サーバーが待ち受けるポート	8080
--host	いいえ、デフォルトは 127.0.0.1	MCP サーバーが待ち受けるホスト IP アドレス	0.0.0.0
--env	いいえ	MCP stdio サーバーに渡す追加の環境変数です。複数回指定できます。	FOO BAR
--cwd	いいえ	MCP stdio サーバーのプロセスに渡す作業ディレクトリです。	/tmp
--pass-environment	いいえ	サーバーの起動時にすべての環境変数を引き継ぎます	--no-pass-environment
--allow-origin	いいえ	SSE サーバーで許可するオリジンです。複数回指定できます。デフォルトでは CORS は許可されません。	--allow-origin "*"
--expose-header	いいえ	Access-Control-Expose-Headers に追加するヘッダーです。複数回指定できます。デフォルトは mcp-session-id です。	--expose-header Custom-Header
--stateless	いいえ	ストリーム可能な http トランスポートでステートレスモードを有効にします。デフォルトは False です	--no-stateless
--named-server NAME COMMAND_STRING	いいえ	名前付き stdio サーバーを定義します。	--named-server fetch 'uvx mcp-server-fetch'
--named-server-config FILE_PATH	いいえ	名前付き stdio サーバーを定義する JSON ファイルのパスです。	--named-server-config /path/to/servers.json
--sse-port (deprecated)	いいえ、利用可能なポートをランダムに選択	SSE サーバーが待ち受けるポート	8080
--sse-host (deprecated)	いいえ、デフォルトは 127.0.0.1	SSE サーバーが待ち受けるホスト IP アドレス	0.0.0.0

2.2 使用例

ポート 8080 で待ち受け、ローカル MCP サーバーに接続する mcp-proxy サーバーを起動するには、次のようにします。

# Start the MCP server behind the proxy
mcp-proxy uvx mcp-server-fetch

# Start the MCP server behind the proxy with a custom port
# (deprecated) mcp-proxy --sse-port=8080 uvx mcp-server-fetch
mcp-proxy --port=8080 uvx mcp-server-fetch

# Start the MCP server behind the proxy with a custom host and port
# (deprecated) mcp-proxy --sse-host=0.0.0.0 --sse-port=8080 uvx mcp-server-fetch
mcp-proxy --host=0.0.0.0 --port=8080 uvx mcp-server-fetch

# Start the MCP server behind the proxy with a custom user agent
# Note that the `--` separator is used to separate the `mcp-proxy` arguments from the `mcp-server-fetch` arguments
# (deprecated) mcp-proxy --sse-port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent
mcp-proxy --port=8080 -- uvx mcp-server-fetch --user-agent=YourUserAgent

# Start multiple named MCP servers behind the proxy
mcp-proxy --port=8080 --named-server fetch 'uvx mcp-server-fetch' --named-server fetch2 'uvx mcp-server-fetch'

# Start multiple named MCP servers using a configuration file
mcp-proxy --port=8080 --named-server-config ./servers.json

# Start the MCP server with CORS enabled and custom exposed headers
mcp-proxy --port=8080 --allow-origin='*' --expose-header Custom-Header uvx mcp-server-fetch

名前付きサーバー

• NAME は URL パス /servers/NAME/ で使用されます。
• COMMAND_STRING はサーバーを起動するコマンドです（例：'uvx mcp-server-fetch'）。
  • 複数回使用できます。
  • --named-server-config を使用する場合、この引数は無視されます。
• FILE_PATH - 指定した場合、名前付きサーバーの定義元はこのファイルのみとなり、--named-server CLI 引数は無視されます。

デフォルトサーバーを指定した場合（--named-server または --named-server-config を指定せずに command_or_url 引数を指定した場合）、ルートパス（例：http://127.0.0.1:8080/sse）からアクセスできます。

名前付きサーバー（--named-server または --named-server-config のどちらで定義した場合も）は、/servers/<server-name>/ 配下からアクセスできます（例：http://127.0.0.1:8080/servers/fetch1/sse）。 /status エンドポイントから全体のステータスを確認できます。

--named-server-config 用 JSON 設定ファイルの形式：

JSON ファイルは次の構造に従う必要があります。

{
  "mcpServers": {
    "fetch": {
      "disabled": false,
      "timeout": 60,
      "command": "uvx",
      "args": [
        "mcp-server-fetch"
      ],
      "transportType": "stdio"
    },
    "github": {
      "timeout": 60,
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      },
      "transportType": "stdio"
    }
  }
}

• mcpServers：各キーがサーバー名（URL パスで使用されます。例：/servers/fetch/）で、値がサーバーを定義するオブジェクトとなる辞書です。
• command：（必須）stdio サーバーを実行するコマンドです。
• args：（任意）コマンドに渡す引数のリストです。デフォルトは空のリストです。
• enabled：（任意）false の場合、このサーバー定義はスキップされます。デフォルトは true です。
• timeout と transportType：これらのフィールドは標準的な MCP クライアント設定に含まれていますが、名前付きサーバーの読み込み時に mcp-proxy では現在無視されます。トランスポートタイプは暗黙的に「stdio」となります。

インストール

PyPI 経由でインストールする

パッケージの安定版は PyPI リポジトリで公開されています。次のコマンドでインストールできます。

# Option 1: With uv (recommended)
uv tool install mcp-proxy

# Option 2: With pipx (alternative)
pipx install mcp-proxy

インストール後、mcp-proxy コマンドでサーバーを実行できます。各モードの設定オプションについては、上記を参照してください。

Github リポジトリ経由でインストールする（最新版）

次のコマンドを使用して、Git リポジトリからパッケージの最新版をインストールできます。

uv tool install git+https://github.com/sparfenyuk/mcp-proxy

メモ

サーバーをすでにインストールしている場合は、uv tool upgrade --reinstall コマンドで更新できます。

メモ

サーバーを削除するには、uv tool uninstall mcp-proxy コマンドを使用してください。

コンテナとしてインストールする

バージョン 0.3.2 以降、対応するコンテナイメージをプルして実行できます。 リリースイメージは、linux/amd64 と linux/arm64 向けのマルチプラットフォームマニフェストとして GHCR と Docker Hub に公開されています。 Docker はホストのアーキテクチャに一致するイメージを自動的に選択します。

docker run --rm -t ghcr.io/sparfenyuk/mcp-proxy:v0.12.0 --help
docker run --rm -t sparfenyuk/mcp-proxy:v0.12.0 --help

トラブルシューティング

• 問題：Claude Desktop がサーバーを起動できず、ログに ENOENT コードが記録される

  解決策：バイナリのフルパスを使用してみてください。そのためには、ターミナルを開いて which mcp-proxy（macOS、Linux）または where.exe mcp-proxy（Windows）コマンドを実行します。次に、出力されたパスを command 属性の値として使用してください。

    "fetch": {
      "command": "/full/path/to/bin/mcp-proxy",
      "args": [
        "http://localhost:8932/sse"
      ]
    }
  

コンテナイメージの拡張

mcp-proxy コンテナイメージを拡張して、実行可能ファイルを追加できます。たとえば、uv はデフォルトでは含まれていませんが、これを含むカスタムイメージを作成できます。

# 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 ["catatonit", "--", "mcp-proxy"]

Docker Compose のセットアップ

カスタム Dockerfile を使って、Docker Compose ファイルにサービスを定義できます。

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

メモ

--pass-environment 引数を設定しないと、「No interpreter found in managed installations or search path」エラーが発生するため、忘れずに設定してください。

コマンドライン引数

usage: mcp-proxy [-h] [--version] [-H KEY VALUE]
                 [--transport {sse,streamablehttp}] [--verify-ssl [VALUE]]
                 [--no-verify-ssl] [-e KEY VALUE] [--cwd CWD]
                 [--client-id CLIENT_ID] [--client-secret CLIENT_SECRET] [--token-url TOKEN_URL]
                 [--pass-environment | --no-pass-environment]
                 [--log-level LEVEL] [--debug | --no-debug]
                 [--named-server NAME COMMAND_STRING]
                 [--named-server-config FILE_PATH] [--port PORT] [--host HOST]
                 [--stateless | --no-stateless] [--sse-port SSE_PORT]
                 [--sse-host SSE_HOST]
                 [--allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]]
                 [--expose-header HEADER]
                 [command_or_url] [args ...]

Start the MCP proxy in one of two possible modes: as a client or a server.

positional arguments:
  command_or_url        Command or URL to connect to. When a URL, will run an SSE/StreamableHTTP client. Otherwise, if --named-server is not used, this will be the command for the default stdio client. If --named-server is used, this argument is ignored for stdio mode unless no default server is desired. See corresponding options for more details.

options:
  -h, --help            show this help message and exit
  --version             Show the version and exit

SSE/StreamableHTTP client options:
  -H, --headers KEY VALUE
                        Headers to pass to the SSE server. Can be used multiple times.
  --transport {sse,streamablehttp}
                        The transport to use for the client. Default is SSE.
  --verify-ssl [VALUE]  Control SSL verification when acting as a client. Use without a value to force verification, pass 'false' to disable, or provide a path to a PEM bundle.
  --no-verify-ssl       Disable SSL verification (alias for --verify-ssl false).
  --client-id CLIENT_ID
                        OAuth2 client ID for authentication
  --client-secret CLIENT_SECRET
                        OAuth2 client secret for authentication
  --token-url TOKEN_URL
                        OAuth2 token URL for authentication
  --username USERNAME   Username for authentication
  --password PASSWORD   Password for authentication
  --digest              Use digest authentication

stdio client options:
  args                  Any extra arguments to the command to spawn the default server. Ignored if only named servers are defined.
  -e, --env KEY VALUE   Environment variables used when spawning the default server. Can be used multiple times. For named servers, environment is inherited or passed via --pass-environment.
  --cwd CWD             The working directory to use when spawning the default server process. Named servers inherit the proxy's CWD.
  --pass-environment, --no-pass-environment
                        Pass through all environment variables when spawning all server processes.
  --log-level LEVEL     Set the log level. Default is INFO.
  --debug, --no-debug   Enable debug mode with detailed logging output. Equivalent to --log-level DEBUG. If both --debug and --log-level are provided, --debug takes precedence.
  --named-server NAME COMMAND_STRING
                        Define a named stdio server. NAME is for the URL path /servers/NAME/. COMMAND_STRING is a single string with the command and its arguments (e.g., 'uvx mcp-server-fetch --timeout 10'). These servers inherit the proxy's CWD and environment from --pass-environment.
  --named-server-config FILE_PATH
                        Path to a JSON configuration file for named stdio servers. If provided, this will be the exclusive source for named server definitions, and any --named-server CLI arguments will be ignored.

SSE server options:
  --port PORT           Port to expose an SSE server on. Default is a random port
  --host HOST           Host to expose an SSE server on. Default is 127.0.0.1
  --stateless, --no-stateless
                        Enable stateless mode for streamable http transports. Default is False
  --sse-port SSE_PORT   (deprecated) Same as --port
  --sse-host SSE_HOST   (deprecated) Same as --host
  --allow-origin ALLOW_ORIGIN [ALLOW_ORIGIN ...]
                        Allowed origins for the SSE server. Can be used multiple times. Default is no CORS allowed.
  --expose-header HEADER
                        Headers to expose via Access-Control-Expose-Headers. Defaults to 'Mcp-Session-Id'. Can be used multiple times.

Examples:
  mcp-proxy http://localhost:8080/sse
  mcp-proxy --no-verify-ssl https://server.local/sse
  mcp-proxy --transport streamablehttp http://localhost:8080/mcp
  mcp-proxy --transport streamablehttp --username user --password pass https://server.local/mcp
  mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
  mcp-proxy --client-id CLIENT_ID --client-secret CLIENT_SECRET --token-url https://auth.example.com/token http://localhost:8080/sse
  mcp-proxy --port 8080 -- your-command --arg1 value1 --arg2 value2
  mcp-proxy --named-server fetch 'uvx mcp-server-fetch' --port 8080
  mcp-proxy your-command --port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE
  mcp-proxy your-command --port 8080 --allow-origin='*'
  mcp-proxy your-command --port 8080 --allow-origin='*' --expose-header Custom-Header

設定ファイルの例

{
  "mcpServers": {
    "fetch": {
      "enabled": true,
      "timeout": 60,
      "command": "uvx",
      "args": [
        "mcp-server-fetch"
      ],
      "transportType": "stdio"
    },
    "github": {
      "timeout": 60,
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      },
      "transportType": "stdio"
    }
  }
}

テスト

mcp-server-fetch サーバーとともに実行して、mcp-proxy サーバーを確認してください。対象サーバーのテストには inspector tool を使用できます。

# Run the stdio server called mcp-server-fetch behind the proxy over SSE
mcp-proxy --port=8080 uvx mcp-server-fetch &

# Connect to the SSE proxy server spawned above using another instance of mcp-proxy given the URL of the SSE server
mcp-proxy http://127.0.0.1:8080/sse

# Send CTRL+C to stop the second server

# Bring the first server to the foreground
fg

# Send CTRL+C to stop the first server