AI 도구에 Pullzip 연결하기

1) Claude Desktop 원클릭

확장 파일(.mcpb)을 받아 더블클릭하면 끝입니다. 7-Zip 엔진이 안에 들어 있어 별도 설치가 필요 없습니다.

확장 파일 내려받기 (.mcpb) · v0.8.9

1. .mcpb 파일을 더블클릭하거나 Claude Desktop → 설정 → 확장 프로그램에 끌어다 놓습니다.
2. 설치 화면에서 허용 폴더(기본: 다운로드)와 읽기 전용 여부를 고릅니다.
3. “다운로드/보고서.zip 열어도 안전해?”라고 물어보세요.

2) 다른 AI 도구 (로컬 stdio)

이 도구들은 “명령을 실행해 서버를 띄우는” 방식으로 MCP를 붙입니다. Pullzip 서버는 위의 .mcpb 안에 들어 있으니, 그걸 풀어서 쓰면 됩니다. Node.js가 설치돼 있어야 합니다.

① 서버 준비 (한 번만)

1. 위 .mcpb 내려받기로 받은 파일의 확장자를 .zip으로 바꾼 뒤, 예를 들어 C:\Pullzip에 압축을 풉니다.
2. 그 안에 server/index.js 와 bin/7z.exe 가 보이면 준비 끝입니다.

② 공통 설정 (mcpServers 형식)

경로와 허용 폴더는 본인 환경에 맞게 바꾸세요.

{
  "mcpServers": {
    "pullzip": {
      "command": "node",
      "args": ["C:/Pullzip/server/index.js", "C:/Users/<당신>/Downloads"],
      "env": { "AF_7Z_FALLBACK": "C:/Pullzip/bin/7z.exe" }
    }
  }
}

③ 도구별 설정 위치

도구	설정 위치
Cursor	~/.cursor/mcp.json 또는 프로젝트 .cursor/mcp.json
VS Code (Copilot)	.vscode/mcp.json — 아래 형식 사용
Cherry Studio · Trae · Kimi Code	앱의 MCP 설정 → “stdio 서버 추가” → 위 JSON 붙여넣기
Gemini CLI · Qwen Code	~/.gemini/settings.json · ~/.qwen/settings.json (같은 형식)
Claude Desktop (수동)	설정 → 개발자 → claude_desktop_config.json

Claude Code

claude mcp add pullzip -e AF_7Z_FALLBACK=C:/Pullzip/bin/7z.exe -- node C:/Pullzip/server/index.js C:/Users/<당신>/Downloads

VS Code (.vscode/mcp.json)

{
  "servers": {
    "pullzip": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Pullzip/server/index.js", "C:/Users/<당신>/Downloads"],
      "env": { "AF_7Z_FALLBACK": "C:/Pullzip/bin/7z.exe" }
    }
  }
}

읽기 전용으로 쓰려면 args 뒤에 --read-only를 더하거나 env에 AF_READ_ONLY=true를 넣으세요.

3) Pullzip API 자가호스팅 HTTP

같은 서버를 HTTP 모드로 띄우면 JSON-RPC(MCP) API가 됩니다. 내 컴퓨터·서버에서만 실행되므로 파일이 밖으로 나가지 않고, 토큰 인증 + 기본 읽기전용이라 안전합니다. ChatGPT·Gemini 앱 같은 원격 클라이언트도 이 주소를 사용합니다.

① 서버 실행

node C:/Pullzip/server/index.js --http --port 8765 C:/Users/<당신>/Downloads

시작하면 콘솔에 접속 주소와 인증 토큰이 출력됩니다:

Pullzip MCP (HTTP) listening on http://127.0.0.1:8765/mcp
auth: "Authorization: Bearer <토큰>"  or secret URL /mcp/<토큰>

② 보안 기본값

• 읽기 전용이 기본 — 쓰기(압축 생성·해제)를 허용하려면 --allow-write.
• 토큰 필수 — 자동 생성되며, --token <값> 또는 AF_TOKEN 환경변수로 고정 가능.
• 지정한 폴더 밖은 접근 불가, 요청 본문 4MB 제한, DNS 리바인딩 보호(허용 Host만 응답).

③ 호출 예시

curl -s http://127.0.0.1:8765/mcp \
  -H "Authorization: Bearer <토큰>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s http://127.0.0.1:8765/health     # {"ok":true}

④ 인터넷에 노출 (ChatGPT · Gemini 앱)

이 서비스들은 공개 HTTPS 주소만 받습니다. 터널을 붙이고 그 도메인을 --public-host로 허용하세요.

node C:/Pullzip/server/index.js --http --port 8765 C:/Users/<당신>/Downloads --public-host <터널도메인>
cloudflared tunnel --url http://127.0.0.1:8765

공식 호스팅 공개 API는 제공하지 않습니다 — 파일이 우리 서버로 업로드되지 않도록, 실행은 항상 본인 환경에서 합니다. 이것이 “업로드 없음” 약속을 지키는 방식입니다.