mcp-프록시
에 대한
mcp-proxy 서버 전송 방식을 전환할 수 있는 도구입니다. 지원되는 모드는 두 가지입니다.
- stdio를 SSE/StreamableHTTP로
- SSE에서 stdio로
1. stdio를 SSE/StreamableHTTP로
stdio에서 원격 SSE 서버에 연결하는 프록시 서버를 실행합니다.
이 모드를 사용하면 Claude Desktop과 같은 클라이언트가 기본적으로 지원되지 않더라도 SSE를 통해 원격 서버와 통신할 수 있습니다.
지엑스피1
1.1 구성
이 모드에서는 MCP 서버의 SSE 엔드포인트 URL을 프로그램의 첫 번째 인수로 제공해야 합니다. 서버가 Streamable HTTP 전송을 사용하는 경우, --transport=streamablehttp 전달하여 mcp-proxy 측에서 Streamable HTTP 전송을 적용해야 합니다.
인수
| 이름 | 필수의 | 설명 | 예 |
|---|
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 서버를 노출하는 프록시 서버를 실행합니다.
이렇게 하면 로컬 stdio 서버에 원격으로 연결할 수 있습니다. mcp-proxy SSE 요청을 수신하기 위해 포트를 열고, MCP 요청을 처리하는 로컬 stdio 서버를 생성합니다.
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 서버에 전달할 추가 환경 변수입니다. 여러 번 사용할 수 있습니다. | 푸 바 |
--cwd | 아니요 | MCP stdio 서버 프로세스에 전달할 작업 디렉토리입니다. | /임시 |
--pass-environment | 아니요 | 서버를 생성할 때 모든 환경 변수를 전달합니다. | --no-pass-environment |
--allow-origin | 아니요 | SSE 서버에 허용되는 출처입니다. 여러 번 사용할 수 있습니다. 기본값은 CORS가 허용되지 않습니다. | --허용-원점 "*" |
--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 /경로/서버/.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 프록시를 자동으로 설치하려면:
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 기본적으로 포함되어 있지 않지만, 이를 사용하여 사용자 지정 이미지를 만들 수 있습니다.
# 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 서버를 실행하여 확인하세요. 검사기 도구를 사용하여 대상 서버를 테스트할 수 있습니다.
# 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