먼저 Node.js 설치

npm install -g @example/mcp-server

~/.claude/claude_desktop_config.json을 수동으로 편집

Claude Desktop 재시작

작동하기를 희망

이후:

1. .mcpb 파일 다운로드

2. Claude Desktop으로 열려면 더블클릭

3. "설치" 클릭

그게 전부입니다. 터미널 없고, 설정 파일 없고, 의존성 충돌도 없습니다.

아키텍처 개요

Desktop Extension는 로컬 MCP 서버와 Claude Desktop 및 데스크톱 확장을 지원하는 다른 애플리케이션이 알아야 할 모든 것을 설명하는 manifest.json을 포함하는 zip 아카이브입니다.

extension.mcpb (ZIP 아카이브)

├── manifest.json # 확장 프로그램 메타데이터 및 설정

├── server/ # MCP 서버 구현

│ └── [server files]

├── dependencies/ # 모든 필요한 패키지/라이브러리

└── icon.png # 선택사항: 확장 프로그램 아이콘

예시: Node.js 확장 프로그램

extension.mcpb

├── manifest.json # 필수: 확장 프로그램 메타데이터 및 설정

├── server/ # 서버 파일

│ └── index.js # 메인 진입점

├── node_modules/ # 번들된 의존성

├── package.json # 선택사항: NPM 패키지 정의

└── icon.png # 선택사항: 확장 프로그램 아이콘

예시: Python 확장 프로그램

extension.mcpb (ZIP 파일)

├── manifest.json # 필수: 확장 프로그램 메타데이터 및 설정

├── server/ # 서버 파일

│ ├── main.py # 메인 진입점

│ └── utils.py # 추가 모듈

├── lib/ # 번들된 Python 패키지

├── requirements.txt # 선택사항: Python 의존성 목록

└── icon.png # 선택사항: 확장 프로그램 아이콘

Desktop Extension에 필수인 유일한 파일은 manifest.json입니다. Claude Desktop은 모든 복잡성을 처리합니다:

• 내장 런타임: Claude Desktop과 함께 Node.js를 제공하여 외부 의존성을 제거합니다
• 자동 업데이트: 새 버전을 사용할 수 있으면 확장 프로그램이 자동으로 업데이트됩니다
• 보안 비밀: API 키와 같은 민감한 설정은 OS 키체인에 저장됩니다

매니페스트에는 이름, 설명, 작성자와 같은 사람이 읽을 수 있는 정보, 기능(도구, 프롬프트) 선언, 사용자 설정 및 런타임 요구사항이 포함됩니다. 대부분의 필드는 선택사항이므로 최소 버전은 꽤 짧지만, 실제로는 세 가지 지원되는 확장 프로그램 유형(Node.js, Python, 클래식 바이너리/실행 파일) 모두가 파일을 포함할 것으로 예상합니다.

{

"mcpb_version": "0.1", // 이 매니페스트가 준수하는 MCPB 사양 버전

"name": "my-extension", // 기계가 읽을 수 있는 이름(CLI, API용)

"version": "1.0.0", // 확장 프로그램의 시맨틱 버전

"description": "A simple MCP extension", // 확장 프로그램이 하는 일에 대한 간단한 설명

"author": { // 작성자 정보(필수)

"name": "Extension Author" // 작성자 이름(필수 필드)

},

"server": { // 서버 설정(필수)

"type": "node", // 서버 유형: "node", "python", "binary"

"entry_point": "server/index.js", // 메인 서버 파일 경로

"mcp_config": { // MCP 서버 설정

"command": "node", // 서버를 실행하는 명령어

"args": [ // 명령어에 전달되는 인수

"${__dirname}/server/index.js" // ${__dirname}은 확장 프로그램의 디렉터리로 대체됨

]

}

}

}

매니페스트 사양에는 로컬 MCP 서버의 설치와 설정을 더 쉽게 만들기 위한 여러 편의 옵션이 있습니다. 서버 설정 객체는 템플릿 리터럴 형태의 사용자 정의 설정과 플랫폼별 재정의 모두에 대한 공간을 만드는 방식으로 정의할 수 있습니다. 확장 프로그램 개발자는 사용자로부터 어떤 종류의 설정을 수집할지 상세하게 정의할 수 있습니다.

매니페스트가 설정을 어떻게 지원하는지 구체적인 예를 살펴보겠습니다. 아래 매니페스트에서 개발자는 사용자가 api_key를 제공해야 한다고 선언합니다. Claude는 사용자가 해당 값을 제공할 때까지 확장 프로그램을 활성화하지 않고, 운영 체제의 비밀 저장소에 자동으로 보관한 다음, 서버를 시작할 때 ${user_config.api_key}를 사용자 제공 값으로 투명하게 대체합니다. 마찬가지로 ${__dirname}은 확장 프로그램의 압축 해제된 디렉터리의 전체 경로로 대체됩니다.

{

"mcpb_version": "0.1",

"name": "my-extension",

"version": "1.0.0",

"description": "A simple MCP extension",

"author": {

"name": "Extension Author"

},

"server": {

"type": "node",

"entry_point": "server/index.js",

"mcp_config": {

"command": "node",

"args": ["${__dirname}/server/index.js"],

"env": {

"API_KEY": "${user_config.api_key}"

}

}

},

"user_config": {

"api_key": {

"type": "string",

"title": "API Key",

"description": "Your API key for authentication",

"sensitive": true,

"required": true

}

}

}

대부분의 선택사항 필드를 포함한 완전한 manifest.json은 다음과 같을 수 있습니다:

{

"mcpb_version": "0.1",

"name": "My MCP Extension",

"display_name": "My Awesome MCP Extension",

"version": "1.0.0",

"description": "A brief description of what this extension does",

"long_description": "A detailed description that can include multiple paragraphs explaining the extension's functionality, use cases, and features. It supports basic markdown.",

"author": {

"name": "Your Name",

"email": "yourname@example.com",

"url": "https://your-website.com"

},

"repository": {

"type": "git",

"url": "https://github.com/your-username/my-mcp-extension"

},

"homepage": "https://example.com/my-extension",

"documentation": "https://docs.example.com/my-extension",

"support": "https://github.com/your-username/my-mcp-extension/issues",

"icon": "icon.png",

"screenshots": [

"assets/screenshots/screenshot1.png",

"assets/screenshots/screenshot2.png"

],

"server": {

"type": "node",

"entry_point": "server/index.js",

"mcp_config": {

"command": "node",

"args": ["${__dirname}/server/index.js"],

"env": {

"ALLOWED_DIRECTORIES": "${user_config.allowed_directories}"

}

}

},

"tools": [

{

"name": "search_files",

"description": "Search for files in a directory"

}

],

"prompts": [

{

"name": "poetry",

"description": "Have the LLM write poetry",

"arguments": ["topic"],

"text": "Write a creative poem about the following topic: ${arguments.topic}"

}

],

"tools_generated": true,

"keywords": ["api", "automation", "productivity"],

"license": "MIT",

"compatibility": {

"claude_desktop": ">=1.0.0",

"platforms": ["darwin", "win32", "linux"],

"runtimes": {

"node": ">=16.0.0"

}

},

"user_config": {

"allowed_directories": {

"type": "directory",

"title": "Allowed Directories",

"description": "Directories the server can access",

"multiple": true,

"required": true,

"default": ["${HOME}/Desktop"]

},

"api_key": {

"type": "string",

"title": "API Key",

"description": "Your API key for authentication",

"sensitive": true,

"required": false

},

"max_file_size": {

"type": "number",

"title": "Maximum File Size (MB)",

"description": "Maximum file size to process",

"default": 10,

"min": 1,

"max": 100

}

}

}

확장 프로그램과 매니페스트를 보려면 MCPB 저장소의 예시를 참조하세요. manifest.json의 모든 필수 및 선택사항 필드에 대한 전체 사양은 오픈소스 툴체인의 일부로 찾을 수 있습니다.

첫 번째 확장 프로그램 구축

기존 MCP 서버를 Desktop Extension으로 패키징하는 과정을 살펴보겠습니다. 간단한 파일 시스템 서버를 예로 사용하겠습니다.

1단계: 매니페스트 생성

먼저 서버용 매니페스트를 초기화하세요:

npx @anthropic-ai/mcpb init

이 대화형 도구는 서버에 대해 묻고 완전한 manifest.json을 생성합니다. 가장 기본적인 manifest.json으로 빠르게 가고 싶다면 --yes 매개변수와 함께 명령어를 실행할 수 있습니다.

2단계: 사용자 설정 처리

서버에 사용자 입력(API 키 또는 허용된 디렉터리 등)이 필요한 경우 매니페스트에서 선언하세요:

"user_config": {

"allowed_directories": {

"type": "directory",

"title": "Allowed Directories",

"description": "Directories the server can access",

"multiple": true,

"required": true,

"default": ["${HOME}/Documents"]

}

}

Claude Desktop은 다음을 수행합니다:

• 사용자 친화적인 설정 UI 표시
• 확장 프로그램을 활성화하기 전에 입력 유효성 검사
• 민감한 값 안전하게 저장
• 개발자 설정에 따라 설정을 인수 또는 환경 변수로 서버에 전달

아래 예에서는 사용자 설정을 환경 변수로 전달하지만 인수일 수도 있습니다.

"server": {

"type": "node",

"entry_point": "server/index.js",

"mcp_config": {

"command": "node",

"args": ["${__dirname}/server/index.js"],

"env": {

"ALLOWED_DIRECTORIES": "${user_config.allowed_directories}"

}

}

}

3단계: 확장 프로그램 패키징

모든 것을 .mcpb 파일로 번들링하세요:

npx @anthropic-ai/mcpb pack

이 명령어는 다음을 수행합니다:

• 매니페스트 유효성 검사
• .mcpb 아카이브 생성

4단계: 로컬 테스트

.mcpb 파일을 Claude Desktop의 설정 창으로 드래그하세요. 다음이 표시됩니다:

• 확장 프로그램에 대한 사람이 읽을 수 있는 정보
• 필수 권한 및 설정
• 간단한 "설치" 버튼

고급 기능

크로스 플랫폼 지원

확장 프로그램은 다른 운영 체제에 맞게 조정할 수 있습니다:

"server": {

"type": "node",

"entry_point": "server/index.js",

"mcp_config": {

"command": "node",

"args": ["${__dirname}/server/index.js"],

"platforms": {

"win32": {

"command": "node.exe",

"env": {

"TEMP_DIR": "${TEMP}"

}

},

"darwin": {

"env": {

"TEMP_DIR": "${TMPDIR}"

}

}

}

}

}

동적 설정

런타임 값에는 템플릿 리터럴을 사용하세요:

기능 선언

사용자가 기능을 미리 이해할 수 있도록 돕습니다:

"tools": [

{

"name": "read_file",

"description": "Read contents of a file"

}

],

"prompts": [

{

"name": "code_review",

"description": "Review code for best practices",

"arguments": ["file_path"]

}

]

확장 프로그램 디렉터리

Claude Desktop에 내장된 큐레이팅된 확장 프로그램 디렉터리를 출시합니다. 사용자는 GitHub를 검색하거나 코드를 검토할 필요 없이 탐색, 검색 및 원클릭으로 설치할 수 있습니다. Desktop Extension 사양과 macOS 및 Windows용 Claude의 구현이 시간이 지남에 따라 계속 발전할 것으로 예상하지만, 확장 프로그램을 창의적인 방식으로 Claude의 기능을 확장하는 데 사용할 수 있는 수많은 방법을 볼 것을 기대합니다.

확장 프로그램을 제출하려면:

• 제출 양식에 있는 지침을 따르세요
• Windows 및 macOS에서 테스트
• 확장 프로그램 제출

우리 팀은 품질과 보안을 검토합니다.

오픈 생태계 구축

우리는 MCP 서버 주변의 오픈 생태계에 전념하며, 여러 애플리케이션과 서비스에서 보편적으로 채택될 수 있는 능력이 커뮤니티에 도움이 되었다고 믿습니다. 이러한 약속에 따라 우리는 Desktop Extension 사양, 툴체인, macOS 및 Windows용 Claude가 자체 Desktop Extension 지원을 구현하는 데 사용하는 스키마와 핵심 함수를 오픈소스로 공개합니다.

우리는 MCPB 형식이 Claude뿐만 아니라 다른 AI 데스크톱 애플리케이션에도 로컬 MCP 서버를 더 휴대하기 쉽게 만들기를 희망합니다.

우리는 다음을 오픈소스로 공개합니다:

• 완전한 MCPB 사양
• 패키징 및 검증 도구
• 참조 구현 코드
• TypeScript 타입 및 스키마

이것은 다음을 의미합니다:

• MCP 서버 개발자용: 한 번 패키징하면 MCPB를 지원하는 모든 곳에서 실행
• 앱 개발자용: 처음부터 구축하지 않고도 확장 프로그램 지원 추가
• 사용자용: 모든 MCP 지원 애플리케이션에서 일관된 경험

사양과 툴체인은 0.1로 버전이 지정되어 있으며, 이는 우리가 더 큰 커뮤니티와 함께 형식을 발전시키고 변경하는 것을 기대하고 있음을 나타냅니다. 여러분의 의견을 들을 것을 기대합니다.

보안 및 기업 고려사항

우리는 특히 기업을 위해 확장 프로그램이 새로운 보안 고려사항을 도입한다는 것을 이해합니다. 우리는 Desktop Extensions 프리뷰 릴리스와 함께 여러 안전장치를 구축했습니다:

사용자용

• 민감한 데이터는 OS 키체인에 유지
• 자동 업데이트
• 설치된 확장 프로그램 감사 가능

기업용

• 그룹 정책(Windows) 및 MDM(macOS) 지원
• 승인된 확장 프로그램 사전 설치 가능
• 특정 확장 프로그램 또는 퍼블리셔 차단
• 확장 프로그램 디렉터리 완전히 비활성화
• 프라이빗 확장 프로그램 디렉터리 배포

조직 내 확장 프로그램 관리 방법에 대한 자세한 내용은 문서를 참조하세요.

시작하기

자신만의 확장 프로그램을 구축할 준비가 되셨나요? 시작하는 방법은 다음과 같습니다:

MCP 서버 개발자용: 개발자 문서를 검토하세요 - 또는 로컬 MCP 서버 디렉터리에서 다음 명령어를 실행하여 바로 시작하세요:

npm install -g @anthropic-ai/mcpb

mcpb init

mcpb pack