Weaviate Claude Skills MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

전체 로컬 Weaviate 수명주기를 포괄하는 5가지 기술
로컬 인스턴스용 Docker-compose 템플릿
일괄 수집 및 파일 기반 가져오기
필터, 하이브리드 검색 및 분석을 사용한 RAG 쿼리
요구사항.txt를 사용한 Python-venv 설정

라이브 데모

실제 사용 모습

weaviate-claude-skills.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "weaviate-claude-skills": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/saskinosie/weaviate-claude-skills",
        "~/.claude/skills/weaviate-claude-skills"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "weaviate-claude-skills": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/saskinosie/weaviate-claude-skills",
        "~/.claude/skills/weaviate-claude-skills"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "weaviate-claude-skills": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/saskinosie/weaviate-claude-skills",
        "~/.claude/skills/weaviate-claude-skills"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "weaviate-claude-skills": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/saskinosie/weaviate-claude-skills",
        "~/.claude/skills/weaviate-claude-skills"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "weaviate-claude-skills",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/saskinosie/weaviate-claude-skills",
        "~/.claude/skills/weaviate-claude-skills"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "weaviate-claude-skills": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/saskinosie/weaviate-claude-skills",
          "~/.claude/skills/weaviate-claude-skills"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add weaviate-claude-skills -- git clone https://github.com/saskinosie/weaviate-claude-skills ~/.claude/skills/weaviate-claude-skills

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Weaviate Claude Skills

한 시간 안에 문서에 로컬 RAG를 설치하세요.

👤 로컬 RAG 프로토타입을 시작하는 개발자 ⏱ ~60 min intermediate

언제 쓸까: 클라우드 공급업체에 문서를 보내지 않고 자신의 문서와 채팅하고 싶습니다.

사전 조건

도커 + 파이썬 3.10+ — Docker Desktop을 설치하십시오. 필요한 경우 pyenv
설치된 스킬 — ~/.claude/skills/에 git 복제

흐름

Docker 시작 Weaviate

weaviate-local-setup을 사용하여 로컬 Weaviate에 대한 docker-compose를 시작합니다.✓ 복사됨

→ docker ps는 8080에서 weaviate healthy를 보여줍니다.
컬렉션 만들기

제목(텍스트), 본문(텍스트), 소스_URL(텍스트) 필드가 포함된 '문서' 컬렉션을 만듭니다.✓ 복사됨

→ 스키마가 적용되었습니다. weaviate-collection-manager가 구성을 반환합니다.
섭취

./docs 아래의 모든 .md를 'Docs'의 개체로 수집합니다.✓ 복사됨

→ 일괄 진행 상황이 보고되었습니다. 쿼리를 통해 표시되는 객체
묻다

weaviate-query-agent 사용: 'API 키를 어떻게 교체하나요?'✓ 복사됨

→ 답변은 Docs 컬렉션의 source_url을 인용합니다.

결과: 반복할 수 있는 실행 가능한 로컬 RAG입니다.

함정

청크 없이 거대한 PDF 전체를 수집 — ~500개 토큰 청크; 기술의 수집 템플릿이 이를 처리하도록 합니다.

함께 쓰기: filesystem

수동 API 호출 없이 컬렉션 스키마 반복

👤 벡터 스키마를 개선하는 팀 ⏱ ~20 min intermediate

언제 쓸까: 초기 RAG - 스키마가 매주 변경되며 컬 명령을 원하지 않습니다.

흐름

현재 스키마 검사

'Docs'에 대한 스키마(필드, 벡터화 도구, 인덱스 구성)를 표시합니다.✓ 복사됨

→ 전체 구성이 반환됨
변화를 제안하다

'언어' 열거형 속성을 추가합니다(en/zh/ja). 나머지는 유지하세요.✓ 복사됨

→ 마이그레이션 계획 + 백업 주의사항
적용하다

적용하다; 기존 500개의 개체를 다시 색인화합니다.✓ 복사됨

→ 작업이 진행됩니다. 개수가 조정되다

결과: 스키마는 재색인 비용을 인식하면서 안전하게 발전했습니다.

함정

재산 철거가 무료라고 가정할 때 — 일부 변경 사항은 다시 포함해야 합니다. 스킬이 저렴할 때와 비쌀 때 표시됩니다.

신뢰할 수 있는 답변을 위한 하이브리드 검색 + 필터

👤 실제 사용자에게 RAG를 전달하는 모든 사람 ⏱ ~15 min intermediate

언제 쓸까: 순수 의미 검색에서는 정확히 일치하는 용어가 누락됩니다. 하이브리드(BM25 + 벡터)가 이를 수정합니다.

흐름

하이브리드 쿼리 실행

'SAML SSO 오류 코드 42'를 쿼리합니다. 알파=0.5(의미 체계 + 키워드 균형)✓ 복사됨

→ 최고 히트작에는 문자 그대로의 '42' 일치 항목뿐만 아니라 개념적으로 관련된 항목도 포함됩니다.
레이어 필터

필터 언어='en'이고 source_url에 '/docs/auth/'가 포함되어 있습니다.✓ 복사됨

→ 조회수가 좁아졌습니다. 답변이 계속 인용됨

결과: 재현율을 잃지 않고 정확한 용어 쿼리에 대한 정밀도가 높아집니다.

함께 쓰기: local-rag

조합

다른 MCP와 조합해 10배 효율

weaviate-claude-skills + filesystem

파일 시스템 MCP를 통해 로컬 파일을 수집한 후 스킬을 통해 쿼리

./docs 아래에 모든 마크다운을 나열하고 Weaviate 'Docs'에 수집한 다음 질문에 대한 하이브리드 검색을 수행합니다.✓ 복사됨

weaviate-claude-skills + local-rag

접근 방식 비교 - 임베딩 전용 vs Weaviate의 구조적 인덱스

이 코퍼스에서는 10개의 평가 질문에 대해 local-rag와 Weaviate 하이브리드를 벤치마킹합니다.✓ 복사됨

weaviate-claude-skills + qdrant

워크로드에 대한 벡터 DB 선택을 평가하세요.

Weaviate 및 Qdrant에서 동일한 평가 세트를 실행합니다. 보고 대기 시간 + MRR.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출
weaviate-local-setup (SKILL)	(none)	처음에만 — 로컬 Weaviate를 불러옵니다.
weaviate-connection (SKILL)	URL + API key	연결 가능성 및 인증 확인
weaviate-collection-manager (SKILL)	schema ops	컬렉션 생성, 검사 또는 발전
weaviate-data-ingestion (SKILL)	object(s) or file paths	단일 삽입, 일괄 삽입 또는 파일 가져오기
weaviate-query-agent (SKILL)	query + filters + alpha	의미/하이브리드 검색 및 RAG 답변

비용 및 제한

운영 비용

API 쿼터: 없음 — Weaviate는 로컬에서 실행됩니다.
호출당 토큰: 쿼리 + 검색된 청크 크기
금액: 현지인은 무료입니다. 나중에 마이그레이션하는 경우 Weaviate Cloud에는 자체 가격이 있습니다.
팁: 의도적으로 청크(~500개 토큰) 너무 큰 청크는 스토리지와 컨텍스트를 모두 낭비합니다.

보안

권한, 시크릿, 파급범위

자격 증명 저장: 스킬 파일이 아닌 .env에서 API 키를 생성합니다. 로컬 개발자는 인증을 건너뛸 수 있지만 포트를 노출하지 마세요.

데이터 외부 송신: 로컬 설정을 위해 컴퓨터를 떠나는 것은 없습니다. Cloud Weaviate는 구성된 엔드포인트로 보냅니다.

많은 이미지에서 기본적으로 Local Weaviate는 0.0.0.0으로 바인딩됩니다. LAN에서 다른 서비스가 실행되는 경우 127.0.0.1로 제한됩니다.
임베딩 모델: 타사 벡터화기를 사용하는 경우 청크가 해당 공급자로 이동합니다. 민감한 데이터의 경우 로컬(예: text2vec-transformers)로 유지하세요.

문제 해결

자주 발생하는 오류와 해결

연결이 거부되었습니다 8080

Weaviate 컨테이너가 실행되지 않습니다. docker는 weaviate-local-setup에서 -d를 구성합니다.

확인: curl localhost:8080/v1/.well-known/ready

스키마 변경 실패

일부 속성 변경에는 컬렉션 재생성이 필요합니다. 내보내기, 삭제, 재생성, 다시 수집.

확인: weaviate-collection-manager diff output

느린 쿼리

HNSW 인덱스 매개변수를 확인하고 벡터화가 올바르게 구성되었는지 확인하십시오. 인덱싱되지 않은 필드에서는 전체 텍스트 대체를 피하세요.

확인: Query explain in the skill's debug mode

대안

Weaviate Claude Skills 다른 것과 비교

대안	언제 쓰나	단점/장점
qdrant	Qdrant의 API와 Rust 성능을 선호합니다.	다른 SDK; 비슷한 능력
local-rag	벡터 DB가 없는 가벼운 로컬 RAG를 원합니다.	유연성이 떨어집니다. 스키마 없음
neo4j	귀하의 데이터는 벡터가 아닌 관계형/그래프입니다.	다른 모델

Weaviate Claude Skills