원문 캡처 · github.com
원문 캡처 · github.com

Web MCP Bridge는 ChatGPT, Gemini, Claude 웹 버전에서 로컬 MCP 서버와 도구를 연결하는 브라우저 확장 프로그램이다. API 키나 추가 구독 없이 사용할 수 있으며, 기본 설정에서는 도구를 호출할 때마다 사용자의 승인을 받는다.

모델이 JSON 블록으로 도구 호출을 요청하면 확장 프로그램이 WebSocket을 통해 로컬 MCP 서버에서 실행하고, 결과를 채팅창에 다시 전달한다. 제작자는 ChatGPT, Gemini, Claude를 지원 플랫폼으로 안내한다. 다른 플랫폼은 지원 목록에 포함되지 않았다.

등록한 서버는 여러 개일 수 있지만 기본적으로 한 번에 하나만 활성화되며, 최대 5개까지 활성화할 수 있다. 모델에는 활성 서버의 도구만 전달된다. 확장 프로그램 팝업에서는 도구가 차지할 토큰 양을 대략 확인할 수 있다. 도구 설명은 JSON Schema 대신 name(param: type) 형식으로 제공하며, 제작자는 이 방식이 토큰을 약 50% 줄인다고 설명한다.

서버별·전체 권한은 ‘항상 허용’, ‘매번 묻기’, ‘허용하지 않음’의 세 가지로 설정할 수 있다. 설정은 팝업과 페이지 안 패널에서 바꾼다. 이미지·오디오·이진 리소스는 실제 파일로 채팅에 첨부되고, 긴 텍스트는 잘라내지 않고 전체를 첨부한다. MCP 서버는 기본 포함되지 않으므로 직접 추가하거나, 한 번의 클릭으로 번들 데모 서버를 추가해야 한다.

확장 프로그램은 숨겨진 페이지에서 제한될 수 있는 페이지 타이머에 의존하지 않으며, 전달 여부를 확인하고 재시도한다. 메시지마다 한 줄 알림을 보내고 주기적으로 전체 안내를 다시 주입해 AI가 도구 사용 방법을 놓치지 않도록 한다고 설명한다. 플랫폼별 어댑터는 선택자 집합으로 구성되며, 새 플랫폼을 추가할 때 약 40줄이 필요하다고 제작자는 안내한다.

Python 브리지는 127.0.0.1에서 요청을 받고 chrome-extension:// 출처만 허용하며 토큰도 지원한다. 제작자는 웹사이트가 도구에 접근할 수 없도록 설계했다고 설명한다. 호출별 ID, 지수형 재시도, MV3 서비스 워커용 연결 유지, 호출 기록, 밝은 테마와 어두운 테마도 포함한다. MCP 호출 결과의 내용은 지시가 아니라 데이터로 AI에 전달해 프롬프트 인젝션을 완화한다고 안내한다.

설치와 사용

브라우저는 로컬 프로그램을 직접 실행할 수 없으므로, 먼저 브리지를 설치한다. 다음 명령은 Windows, macOS, Linux에서 로그인할 때 브리지가 백그라운드로 실행되도록 설정한다.

bash
python server/install_service.py

그다음 확장 프로그램을 불러온다. 팝업이나 페이지 안 패널의 기본 스위치로 브리지를 켜고 끌 수 있으며, 꺼져 있으면 아이콘에 OFF가 표시된다. 자동 시작 설정을 제거하려면 다음 명령을 실행한다.

bash
python server/install_service.py --uninstall

데모 서버를 실행하고 확장 프로그램을 연결하는 빠른 시작 절차는 다음과 같다.

bash
pip install -r server/requirements.txt
python server/mcp_ws_bridge.py --port 8080 --name demo -- python server/examples/demo_mcp_server.py
  1. chrome://extensions에서 개발자 모드를 켜고 ‘압축해제된 확장 프로그램을 로드’를 선택한 뒤 이 폴더를 지정한다.
  2. 팝업에서 서버를 추가한다. 예를 들어 이름을 astrax_mcp, 주소를 ws://localhost:8080으로 입력하거나 ‘데모 서버 추가’를 누른다.
  3. ChatGPT, Gemini 또는 Claude를 열고 왼쪽 아래의 Web MCP Bridge 패널에서 ‘지침 주입’을 선택한다.
  4. “What time is it? Use your tools.”라고 요청하고 도구 호출을 승인한다.

자신의 서버를 실행하려면 다음 명령을 사용할 수 있다.

bash
python server/mcp_ws_bridge.py --port 8080 -- python -m astrax_mcp

여러 서버를 함께 설정하는 방법은 server/servers.example.json과 --config 옵션을 참고한다. 빠른 시작 안내는 저장소의 Quick start에 있다.

도구 호출은 다음 형식의 JSON 블록으로 전달된다.

json
{ "mcp_call": { "server": "server_name", "name": "tool_name", "arguments": { "arg1": "value" } } }

결과는 [MCP_RESULT server="…" tool="…" status="ok|error|rejected"] … [/MCP_RESULT] 형식으로 돌아온다. 자세한 아키텍처 그림과 보안 모델, 선택자 수정 안내, 로드맵은 스페인어 README에 있다.

개발용 명령은 다음과 같다. npm test는 구문, 파서, 프롬프트 빌더와 브리지 통합 테스트를 실행하고, npm run pack은 dist/web-mcp-bridge.zip을 만든다.

bash
npm test # syntax, parser, prompt builder and bridge integration tests
npm run pack # dist/web-mcp-bridge.zip

파일 시스템 접근 권한이 있는 도구는 허용된 파일을 읽을 수 있으므로, 신뢰하는 MCP 서버만 연결해야 한다. 기여 방법은 CONTRIBUTING.md에서 확인할 수 있으며, 제작자는 새 어댑터를 첫 기여로 제안한다. 프로젝트는 MIT 라이선스로 공개됐다(라이선스).

부록: 원문 예시

text
[MCP_RESULT server="…" tool="…" status="ok|error|rejected"] … [/MCP_RESULT]