MCP 게이트웨이

특허

이 프로젝트는 GNU General Public License v3.0에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요.

프로젝트 개요

MCP Gateway는 Python으로 구축된 애플리케이션입니다. 여러 백엔드 MCP 서버(Stdio 또는 SSE 프로토콜을 통해 통신)에 연결하고 기능을 집계하는 중앙 게이트웨이 역할을 합니다. 궁극적으로, 이러한 집계된 기능은 통합 SSE 엔드포인트( /sse )를 통해 업스트림 MCP 클라이언트에 노출됩니다.

핵심 장점:

간소화된 클라이언트 구성: MCP 클라이언트는 MCP 게이트웨이의 단일 주소에만 연결하여 모든 백엔드 서비스 기능에 액세스하므로 각 백엔드 서버를 개별적으로 구성할 필요가 없습니다.
기능 집계 및 오케스트레이션: 다양한 소스의 다양한 기능을 갖춘 MCP 도구를 집계하여 특정 작업 도메인에 초점을 맞춘 보다 강력하고 맞춤형 에이전트를 구축하기 위한 기반을 제공합니다.

프로젝트 파일 구조

지엑스피1

내장형 MCP 서버

이 프로젝트에는 추가 구성 없이 config.json 에서 직접 사용하고 활성화할 수 있는 4개의 백엔드 MCP 서버 도구가 포함되어 있습니다.

Bash 명령 실행 도구( bash_server.py ) : Linux, macOS 또는 WSL 환경에서 Bash 명령을 실행합니다.
Windows CMD 명령 실행 도구( cmd_server.py ) : Windows 환경에서 CMD 명령을 실행합니다.
Windows PowerShell 명령 실행 도구( powershell_server.py ) : Windows 환경에서 PowerShell 명령을 실행합니다.
Windows WMI 쿼리 도구( wmi_server.py ) : Windows 환경에서 WMI 쿼리를 실행합니다.

Linux 환경에서 다음 오류가 발생하는 경우:
error: Distribution `pywin32==310 @ registry+https://pypi.org/simple` can't be installed because it doesn't have a source distribution or wheel for the current platform>
wmi 모듈을 제거하세요: uv remove wmi

설치 및 설정

이 프로젝트는 Python으로 작성되었습니다. 환경 및 종속성 관리를 위해 uv 사용하는 것이 좋습니다.

복제 저장소
git clone https://github.com/trtyr/MCP-Gateway.git cd MCP-Gateway
가상 환경 생성 및 활성화
# Create virtual environment uv venv # Activate virtual environment # Linux/macOS source .venv/bin/activate # Windows (Command Prompt/PowerShell) .venv\Scripts\activate
종속성 설치
# Install all required dependencies based on pyproject.toml uv sync

이러한 단계를 완료하면 프로젝트를 실행할 준비가 됩니다.

빠른 시작

프로젝트 도움말 받기

-h 또는 --help 인수를 사용하면 사용 가능한 모든 시작 옵션을 볼 수 있습니다.

# Windows
uv run python .\main.py -h
# Linux/macOS
uv run python ./main.py -h

출력은 다음과 유사합니다.

usage: main.py [-h] [--host HOST] [--port PORT] [--log-level {debug,info,warning,error,critical}]

Start MCP_Bridge_Server v3.0.0

options:
  -h, --help            show this help message and exit
  --host HOST           Host address (default: 0.0.0.0)
  --port PORT           Port (default: 9000)
  --log-level {debug,info,warning,error,critical}
                        Set file logging level (default: info)

프로젝트 시작하기

uv run python main.py 사용하여 서버를 시작합니다. host , port , log-level 지정할 수 있습니다.

# Listen on all network interfaces on port 9000, set log level to debug
uv run python .\main.py --host 0.0.0.0 --port 9000 --log-level debug

시작하면 아래 이미지와 유사한 Rich로 꾸며진 콘솔 출력이 표시되며, 여기에는 서버 상태, 연결 정보, 로드된 도구가 표시됩니다.

MCP 클라이언트 연결

MCP Gateway를 시작한 후에는 MCP 호환 클라이언트(예: Cline, Cursor, Claude Desktop 또는 사용자 지정 클라이언트)를 사용하여 Gateway에서 제공하는 SSE 엔드포인트에 연결할 수 있습니다.

기본 주소는 http://<Server_IP_Address>:9000/sse 입니다(기본 포트를 사용하는 경우).

예시(ChatWise Connect 사용):

SSE 연결 유형을 선택하세요.
게이트웨이의 SSE URL을 입력합니다(예: http://127.0.0.1:9000/sse ).
Connect 클릭합니다.

연결이 성공적으로 완료되면 클라이언트의 Gateway를 통해 집계된 모든 백엔드 MCP 도구를 볼 수 있습니다.

로그

런타임 로그는 프로젝트 루트 디렉터리의 logs 폴더에 자동으로 저장됩니다. 로그 파일 이름에는 타임스탬프와 로그 수준이 포함되어 있어 문제를 쉽게 추적할 수 있습니다.

logs/
├── log_20240801_103000_INFO.log
└── log_20240801_110000_DEBUG.log
...

구성 파일( `config.json` )

핵심 구성 파일 config.json 프로젝트 루트 디렉터리에 있습니다. 이 파일은 MCP Gateway가 연결하고 관리해야 하는 백엔드 MCP 서버를 정의합니다.

각 항목은 백엔드 서버를 나타냅니다. 키는 해당 백엔드 서버에 할당하는 고유 이름 (이 이름은 해당 기능의 접두사 로 사용됨)이고, 값은 서버 구성을 포함하는 객체입니다.

두 가지 유형의 백엔드 서버 연결이 지원됩니다.

stdio : 표준 입출력(stdin/stdout)을 통해 로컬에서 시작된 MCP 서버 프로세스와 통신합니다.
sse : SSE(Server-Sent Events) 프로토콜을 통해 원격 또는 로컬로 실행되는 MCP 서버와 통신합니다.

Stdio 유형 구성

게이트웨이에서 수명 주기를 관리해야 하는 로컬 MCP 서버 프로세스에 적합합니다.

구성 필드:

type (필수): "stdio" 여야 합니다.
command (필수): 서버 프로세스를 시작하는 데 사용되는 실행 가능 명령(예: python , uv , node 또는 스크립트/실행 파일의 절대 경로).
args (필수): command 에 전달되는 인수 목록(문자열 목록)입니다.
env (선택 사항): 자식 프로세스에 설정할 환경 변수 사전(Dict[str, str]). 생략하면 자식 프로세스는 Gateway의 환경을 상속합니다.

예:

{
  "powershell": {
    "type": "stdio",
    "command": "python",
    "args": ["servers/powershell_server.py"]
  },
  "my_custom_tool": {
    "type": "stdio",
    "command": "/path/to/my/custom_mcp_server",
    "args": ["--port", "ignored_for_stdio", "--some-flag"],
    "env": {
      "API_KEY": "your_secret_key"
    }
  }
}

작동 방식: MCP Gateway가 시작되면 지정된 command 과 args (선택 사항인 env 포함)를 사용하여 자식 프로세스를 시작합니다. Gateway는 이 자식 프로세스의 표준 입출력(SIO)을 통해 백엔드 MCP 서버와 통신합니다. Gateway가 종료되면 이러한 자식 프로세스의 종료를 시도합니다.

SSE 유형 구성

이미 실행 중인 MCP 서버(로컬 또는 원격)에 연결하는 데 적합하거나 Gateway가 연결하기 전에 로컬 SSE 서버 프로세스를 시작해야 하는 경우에 적합합니다.

구성 필드:

type (필수): "sse" 여야 합니다.
url (필수): 백엔드 MCP 서버의 SSE 엔드포인트 URL(전체 HTTP/HTTPS 주소).
command (선택 사항): 지정된 경우 Gateway는 시작 시 이 명령을 실행하여 로컬 SSE 서버를 시작합니다.
args (선택 사항, command 지정된 경우에만 해당): command 에 전달되는 인수 목록입니다.
env (선택 사항, command 지정된 경우에만 해당): 로컬에서 시작된 자식 프로세스에 설정할 환경 변수입니다.

예제 1: 이미 실행 중인 원격 SSE 서버에 연결

{
  "remote_search_service": {
    "type": "sse",
    "url": "https://mcp.example.com/search/sse"
  }
}

예 2: Gateway는 로컬 SSE 서버를 시작하고 연결합니다.

{
  "local_sse_server": {
    "type": "sse",
    "url": "http://127.0.0.1:8080/sse",
    "command": "uv",
    "args": ["run", "python", "servers/my_local_sse_app.py", "--port", "8080"],
    "env": { "MODE": "production" }
  }
}

작동 원리:

지정된 url 만 제공됨 : 게이트웨이는 지정된 url 에 직접 연결을 시도합니다.
url , command , 제공된 args : 게이트웨이는 먼저 command 와 args 사용하여 로컬 프로세스를 시작합니다(이 프로세스가 url 에 해당하는 주소와 포트에서 수신 대기할 것으로 예상). 그런 다음 url 에 연결을 시도하기 전에 잠시 대기합니다( client_manager.py 에 정의된 LOCAL_SSE_STARTUP_DELAY ). 게이트웨이가 종료되면 이 로컬 프로세스를 종료하려고 시도합니다.

구성 추가 예

다음은 config.json 에 타사 MCP 서버를 추가하는 방법에 대한 예입니다.

Stdio 예제: Playwright MCP

Playwright의 MCP 서버( @playwright/mcp )를 통합하고 싶다고 가정해 보겠습니다.

시작 방법 이해 : Playwright MCP는 일반적으로 npx @playwright/mcp@latest 사용하여 시작됩니다. 이는 npx 통해 실행되는 Node.js 패키지입니다.
config.json 구성합니다 :
{ // ... other server configurations ... "playwright": { "type": "stdio", "command": "npx", "args": ["@playwright/mcp@latest"] } // ... other server configurations ... }
여기서 command 는 npx 이고, args 에는 Playwright MCP 패키지 이름과 버전이 포함되어 있습니다.
Gateway 재시작 : config.json 저장하고 MCP Gateway를 재시작합니다.

시작하면 콘솔 로그와 클라이언트에 playwright/... (예: playwright/browse )라는 이름의 도구가 표시되어야 합니다.

SSE 예: ENScan_GO(로컬 시작)

./enscan --mcp 로 시작할 수 있고 http://localhost:8080 에서 SSE 서비스를 제공하는 Go 프로그램인 ENScan_GO를 통합하고 싶다고 가정해 보겠습니다.

실행 파일 가져오기 : ENScan_GO 실행 파일(예: enscan-v1.2.1-windows-amd64.exe )을 다운로드하여 접근 가능한 위치(예: servers/ 디렉토리 또는 시스템 PATH)에 넣습니다.
config.json 구성합니다 :
{ // ... other server configurations ... "enscan": { "type": "sse", "url": "http://127.0.0.1:8080/sse", // Address ENScan_GO listens on // Note: Ensure path separators are correct on Windows, or use an absolute path "command": "servers/enscan-v1.2.1-windows-amd64.exe", // Path to the executable "args": ["--mcp"] // Startup arguments } // ... other server configurations ... }
여기서는 type``sse 로 지정하고, 수신하는 url 을 제공하고, command 와 args 사용하여 Gateway에 이 로컬 SSE 서버를 시작하는 방법을 알려줍니다.
Gateway 재시작 : config.json 저장하고 MCP Gateway를 재시작합니다.

Gateway는 먼저 ENScan_GO 프로세스를 시작한 다음 http://127.0.0.1:8080/sse 에 연결합니다. 시작 후 enscan/... 라는 이름의 도구가 표시됩니다.

MCP-Gateway

Integrations