mcp-プロキシ
について
mcp-proxyサーバートランスポートを切り替えるためのツールです。サポートされているモードは2つあります。
- stdio から SSE/StreamableHTTP へ
- SSEからstdioへ
1. stdio から SSE/StreamableHTTP へ
リモート SSE サーバーに接続するプロキシ サーバーを stdio から実行します。
このモードでは、Claude Desktop などのクライアントは、ネイティブではサポートされていない場合でも、SSE 経由でリモート サーバーと通信できます。
1.1 構成
このモードでは、MCPサーバーのSSEエンドポイントのURLをプログラムの最初の引数として指定する必要があります。サーバーがStreamable HTTPトランスポートを使���している場合は、 mcp-proxy側で--transport=streamablehttpを指定してこれを強制してください。
議論
| 名前 | 必須 | 説明 | 例 |
|---|
command_or_url | はい | 接続するMCPサーバーのSSEエンドポイント | http://example.io/sse |
--headers | いいえ | MCP サーバーの SSE 接続に使用するヘッダー | 承認「Bearer my-secret-access-token」 |
--transport | いいえ | MCPサーバーに接続する際に使用するトランスポートプロトコルを決定します。「sse」または「streamablehttp」のいずれかになります。 | ストリーミング可能なhttp |
環境変数
| 名前 | 必須 | 説明 | 例 |
|---|
API_ACCESS_TOKEN | いいえ | --headers Authorization 'Bearer <API_ACCESS_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 サーバーを公開するプロキシ サーバーを実行します。
これにより、ローカル標準入出力サーバーへのリモート接続が可能になります。mcp mcp-proxy SSE リクエストをリッスンするためのポートを開き、MCP リクエストを処理するローカル標準入出力サーバーを起動します。
2.1 構成
このモードでは、 --sse-port引数を設定する必要があります。-- --sse-host引数は、SSE サーバーが listen するホストの IP アドレスを指定するために使用できます。-- --env引数を使用して、追加の環境変数をローカル stdio サーバーに渡すことができます。ローカル stdio サーバーのコマンドライン引数は、 --区切り記号の後に渡す必要があります。
議論
| 名前 | 必須 | 説明 | 例 |
|---|
command_or_url | はい | MCP stdioサーバーを起動するコマンド | uvx mcp-server-fetch |
--port | いいえ、ランダムに利用可能です | リッスンするMCPサーバーポート | 8080 |
--host | いいえ、デフォルトでは127.0.0.1 | MCP サーバーが listen するホスト IP アドレス | 0.0.0.0 |
--env | いいえ | MCP stdio サーバーに渡す追加の環境変数。複数回使用できます。 | フーバー |
--cwd | いいえ | MCP stdio サーバー プロセスに渡す作業ディレクトリ。 | /tmp |
--pass-environment | いいえ | サーバーの起動時にすべての環境変数を渡す | --no-pass-environment |
--allow-origin | いいえ | SSEサーバーで許可されるオリジン。複数回使用できます。デフォルトではCORSは許可されません。 | --allow-origin "*" |
--stateless | いいえ | ストリーミング可能なHTTPトランスポートのステートレスモードを有効にします。デフォルトはFalseです。 | --ステートレスなし |
--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 (非推奨) | いいえ、ランダムに利用可能です | リッスンするSSEサーバーポート | 8080 |
--sse-host (非推奨) | いいえ、デフォルトでは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
名前付きサーバー
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"
],
"transportType": "stdio"
}
}
}
mcpServers : 各キーがサーバー名 (URL パスで使用される、例: /servers/fetch/ ) であり、値がサーバーを定義するオブジェクトである辞書。command : (必須) stdio サーバーに対して実行するコマンド。args : (オプション) コマンドの引数のリスト。デフォルトは空のリストです。enabled : (オプション) falseの場合、このサーバー定義はスキップされます。デフォルトはtrueです。timeoutとtransportType : これらのフィールドは標準の MCP クライアント設定に存在しますが、現在mcp-proxyは名前付きサーバーのロード時に無視します。トランスポートタイプは暗黙的に「stdio」になります。
インストール
Smithery経由でインストール
Smithery経由で Claude Desktop 用の MCP Proxy を自動的にインストールするには:
npx -y @smithery/cli install mcp-proxy --client claude
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
[!NOTE] サーバーをすでにインストールしている場合は、 uv tool upgrade --reinstallコマンドを使用して更新できます。
[!NOTE] サーバーを削除する場合は、 uv tool uninstall mcp-proxyコマンドを使用します。
コンテナとしてインストール
バージョン 0.3.2 以降では、対応するコンテナ イメージをプルして実行できます。
docker run -t ghcr.io/sparfenyuk/mcp-proxy:v0.3.2-alpine --help
トラブルシューティング
- 問題: Claude Desktop がサーバーを起動できません: ログに ENOENT コードが記録されています解決策：バイナリへのフルパスを使用してください。ターミナルを開き、コマンド
where 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はデフォルトでは含まれていませんが、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 [ "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"
[!NOTE] --pass-environment引数を設定することを忘れないでください。そうしないと、「管理対象インストールまたは検索パスにインタープリターが見つかりません」というエラーが発生します。
コマンドライン引数
usage: mcp-proxy [-h] [-H KEY VALUE] [--transport {sse,streamablehttp}] [-e KEY VALUE] [--cwd CWD] [--pass-environment | --no-pass-environment]
[--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 ...]]
[command_or_url] [args ...]
Start the MCP proxy.
It can run as an SSE client (connecting to a remote SSE server and exposing stdio).
Or, it can run as an SSE server (connecting to local stdio command(s) and exposing them over SSE).
When running as an SSE server, it can proxy a single default stdio command or multiple named stdio commands (defined via CLI or a config file).
positional arguments:
command_or_url Command or URL.
If URL (http/https): Runs in SSE/StreamableHTTP client mode.
If command string: Runs in SSE server mode, this is the default stdio server.
If --named-server or --named-server-config is used, this can be omitted if no default server is desired.
options:
-h, --help show this help message 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.
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.
--debug, --no-debug Enable debug mode with detailed logging output.
--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. Can be specified multiple times. Ignored if --named-server-config is used.
--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.
Examples:
mcp-proxy http://localhost:8080/sse
mcp-proxy --transport streamablehttp http://localhost:8080/mcp
mcp-proxy --headers Authorization 'Bearer YOUR_TOKEN' http://localhost:8080/sse
mcp-proxy --port 8080 -- my-default-command --arg1 value1
mcp-proxy --port 8080 --named-server fetch1 'uvx mcp-server-fetch' --named-server tool2 'my-custom-tool --verbose'
mcp-proxy --port 8080 --named-server-config /path/to/servers.json
mcp-proxy --port 8080 --named-server-config /path/to/servers.json -- my-default-command --arg1
mcp-proxy --port 8080 -e KEY VALUE -e ANOTHER_KEY ANOTHER_VALUE -- my-default-command
mcp-proxy --port 8080 --allow-origin='*' -- my-default-command
設定ファイルの例
{
"mcpServers": {
"fetch": {
"enabled": true,
"timeout": 60,
"command": "uvx",
"args": [
"mcp-server-fetch"
],
"transportType": "stdio"
},
"github": {
"timeout": 60,
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"transportType": "stdio"
}
}
}
テスト
mcp-server-fetchサーバーでmcp-proxyサーバーを実行して確認します。inspectorツールを使用してターゲットサーバーをテストできます。
# 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