MCPB로 로컬 MCP 서버를 Claude Desktop 원클릭 확장으로 만들기

Anthropic 공식 문서. MCPB(.mcpb)는 로컬 MCP 서버와 manifest.json을 담은 zip 하나로, Claude Desktop이 브라우저 확장처럼 설치하는 방법입니다.(파일 더블클릭, 창에 드래그, 또는 Settings → Extensions → Advanced settings → Install Extension…). 서버는 사용자 PC에서 stdio로 돌아 로컬 파일·로컬 도구·방화벽 안 시스템에 닿고, 클라우드 인프라가 없고, 오프라인에서 동작하고, OAuth가 필요 없습니다.

• 개발 방법

언어: Node.js 권장. macOS·Windows용 Claude Desktop에 Node 런타임이 포함되어 있어 사용자가 따로 설치할 것은 없습니다. Python·바이너리 서버도 가능.

빌드: npm install -g @anthropic-ai/mcpb → mcpb init(매니페스트 생성) → mcpb pack(번들). 매니페스트에는 server(type, entry_point, mcp_config의 command/args/env, ${__dirname}·${user_config.*} 치환), user_config(설정 UI 자동 생성, sensitive 값은 OS 보안 저장소에 암호화), compatibility(darwin/win32), 아이콘(512×512 PNG 권장).

MCPB vs 원격 커넥터 선택표: 방화벽 안 시스템, 로컬 도구(Docker·IDE·DB), 기존 SSO·브라우저 세션 인증, "기기 밖으로 나가면 안 되는 작업"은 MCPB. 웹·모바일까지 한 번에 배포하고 중앙에서 업데이트해야 하면 원격 커넥터.

배포: 디렉터리의 확장 등록은 중단(deprecated). .mcpb 파일을 직접 전달하거나 플러그인에 포함해 배포. 설치는 사용자별.

전체 스펙과 예제는 modelcontextprotocol/mcpb 저장소, 아키텍처 배경은 Anthropic 엔지니어링 블로그 "Desktop Extensions".

• 직접 붙여 보며 확인한 것 (Windows, Claude Desktop 2.19675, 2026-10-05) — 문서에 없는 함정

user_config의 file 타입은 임의 경로를 받지 못한다. 설정 화면이 번들 안의 파일만 보이는 선택기를 열어, 사용자 PC의 실행 파일 경로를 줄 수 없었다. 경로가 필요하면 string 타입으로 받아 직접 입력하게 하는 쪽으로 해야합니다.

런처가 서버를 stdio: 'inherit'로 spawn하면 죽습니다. mcp_config.command를 node ${__dirname}/launcher.js로 두고 런처가 실제 서버 프로세스를 띄우는 구조에서, Desktop의 유틸리티 프로세스 아래 손자 프로세스에는 stdin이 닿지 않아 서버가 EOF를 읽고 1.5초 안에 종료됩니다.

해법은 두가지입니다.

(a) mcp_config.command에 서버 실행 파일을 직접 지정한다. 그러면 Desktop이 일반 프로세스("basic execution")로 띄웁니다.

(b) 런처를 유지하되 stdin/stdout을 pipe로 받아 서버로 중계합니다.

(a)처럼 직접 실행하면 mcp_config.env의 ${user_config.*} 치환이 서버에 전달되지 않습니다.(저희 매니페스트에서의 관찰). 설정값을 서버가 꼭 받아야 하면 (b) 런처 경로를 쓰거나 번들 생성 시점에 값을 박아 넣습니다.

Claude in Chrome(브라우저 확장)은 Desktop의 로컬 MCP 서버를 보지 못합니다. 사이드패널은 자기 브라우저 도구와 claude.ai 계정의 커넥터만 나열하고, 로컬 도구를 쓰려면 "원격 MCP URL(공개 주소 + 키)"로 연결하라고 제안합니다. 로컬 전용 서버에는 맞지 않습니다.(저희 케이스)

반대로 같은 PC에 연결된 claude.ai 세션에서는 로컬 서버가 잘 보입니다. Claude Desktop의 로컬 MCP 브리지를 통해 도구 4개가 나열되고 호출됩니다.(관찰). 지원 문서는 아직 "claude_desktop_config.json의 로컬 서버는 claude.ai에서 쓸 수 없다"고 적고 있어서 최근 Desktop 버전에서 바뀐 부분으로 보입니다. 로컬 서버가 어디까지 보이는지는 직접 확인하고 쓰는 편이 안전합니다.

저희가 만들고 있는 로컬 메모리 레이어(project veneta)를 Claude Desktop과 Chrome에 붙이면서 하루 동안 겪은 기록입니다. 시도 순서와 결과는 https://project.veneta.ai/ko/chrome/ 에 정리했고, 코드는 2026-11-24 v0.1과 함께 공개됩니다.