크로마 MCP 서버

ChromaDB를 사용하여 의미론적 검색 및 문서 관리 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 통해 LLM은 직관적인 유사도 지표를 사용하여 문서 컬렉션에 대한 자연어 쿼리를 수행할 수 있으므로, RAG(Retrieval Augmented Generation) 애플리케이션에 이상적입니다.

특징

의미 검색 : 최첨단 임베딩을 사용하여 의미에 따라 문서를 찾습니다.
직관적 유사성 측정 항목 : 결과에는 인간 친화적 유사성 점수(0~100%)가 포함됩니다.
문서 관리 : 문서 및 컬렉션에 대한 전체 CRUD 작업
풍부한 메타데이터 지원 : 사용자 정의 메타데이터 필드로 첨부 및 검색
영구 저장소 : SQLite 백엔드를 사용한 안정적인 문서 저장소
보안 : 구성 가능한 액세스 제어 및 입력 검증
오류 처리 : 포괄적인 오류 메시지 및 우아한 장애 복구

요구 사항

Python 3.12 이상
ChromaDB 0.4.22 이상
MCP Python SDK 1.1.2 이상
uv 패키지 관리자(권장) 또는 pip

빠른 시작

지엑스피1

Claude Desktop 통합에 대해서는 설치를 참조하세요.

건축학

서버는 다음을 기반으로 구축되었습니다.

벡터 저장 및 검색을 위한 ChromaDB
서버 구현을 위한 MCP Python SDK
영구 저장소를 위한 SQLite

데이터 흐름

문서는 ChromaDB의 기본 임베딩 모델을 사용하여 임베딩됩니다.
임베딩과 메타데이터는 ChromaDB의 SQLite 백엔드에 저장됩니다.
쿼리는 동일한 임베딩 모델을 통해 처리됩니다.
결과는 0~100% 유사도 척도로 정규화됩니다.

구성 요소

컬렉션 및 문서

서버는 두 가지 주요 리소스 유형을 관리합니다.

컬렉션 : 공유 임베딩 설정이 있는 관련 문서의 컨테이너
문서 : 메타데이터와 자동 생성된 임베딩이 포함된 텍스트 콘텐츠

도구

컬렉션 관리

list-collections : 사용 가능한 모든 컬렉션을 나열합니다.
create-collection : 선택적인 설정으로 새로운 컬렉션을 생성합니다.
delete-collection : 컬렉션과 해당 문서를 삭제합니다.

문서 작업

add-document : 콘텐츠와 메타데이터를 포함한 새 문서 추가
get-document : ID로 특정 문서를 검색합니다.
update-document : 문서 내용이나 메타데이터를 수정합니다.
delete-document : 컬렉션에서 문서를 제거합니다.
search-documents : 정규화된 유사도 점수를 사용한 의미 검색

설치

필수 조건

파이썬 3.12+
uv 패키지 관리자(권장) 또는 pip

설정

저장소를 복제합니다.

git clone https://github.com/privetin/mcp-server-chroma.git
cd mcp-server-chroma

가상 환경을 만들고 활성화하세요.

uv venv
# On Windows:
.venv\Scripts\activate
# On Unix:
source .venv/bin/activate

종속성 설치:

uv pip install -e .

Claude 데스크톱 통합

Claude Desktop 구성에 서버를 추가합니다.

윈도우 ( %APPDATA%/Claude/claude_desktop_config.json ):

{
  "mcpServers": {
    "chroma": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\mcp-server-chroma",
        "run",
        "mcp-server-chroma"
      ]
    }
  }
}

MacOS ( ~/Library/Application Support/Claude/claude_desktop_config.json ):

{
  "mcpServers": {
    "chroma": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-chroma",
        "run",
        "mcp-server-chroma"
      ]
    }
  }
}

사용 예

컬렉션 관리

컬렉션을 만드세요:

Tool: create-collection
Args: {"name": "research-papers"}

컬렉션 목록:

Tool: list-collections
Args: {}

문서 작업

문서 추가:

Tool: add-document
Args: {
  "collection": "research-papers",
  "content": "Recent advances in transformer architectures have led to significant improvements in natural language processing tasks.",
  "metadata": {
    "title": "Transformer Architectures",
    "year": 2024,
    "category": "ML"
  }
}

특정 문서를 받으세요:

Tool: get-document
Args: {
  "collection": "research-papers",
  "document_id": "doc_123"
}

문서 업데이트:

Tool: update-document
Args: {
  "collection": "research-papers",
  "document_id": "doc_123",
  "content": "Updated findings on transformer architectures show improvements in both efficiency and accuracy.",
  "metadata": {
    "title": "Transformer Architectures - Updated",
    "year": 2024,
    "category": "ML",
    "status": "updated"
  }
}

문서 검색:

Tool: search-documents
Args: {
  "collection": "research-papers",
  "query": "What are the latest developments in transformers?",
  "n_results": 3
}

유사성 점수 이해

검색 결과에는 0~100%의 정규화된 유사도 점수가 포함됩니다.

90-100% : 거의 동일한 콘텐츠 또는 매우 강력한 의미적 일치
70-89% : 의미적 유사성이 강하고 관련성이 높음
50-69% : 부분적인 의미 중복이 있는 중간 정도의 관련성
30-49% : 최소한의 의미적 연결로 다소 관련됨
0-29% : 관련성이 없거나 의미적 연결이 매우 약함

문제 해결

일반적인 문제

데이터베이스 연결 오류
- 데이터베이스 경로가 쓰기 가능한지 확인하세요
- 다른 프로세스가 데이터베이스를 사용하고 있는지 확인하세요
- .chroma 디렉토리를 삭제하고 다시 시작해 보세요.
메모리 문제
- 대규모 컬렉션에는 더 많은 RAM이 필요할 수 있습니다.
- 더 작은 배치 크기를 사용하는 것을 고려하세요
- --log-level DEBUG 로 메모리 사용량 모니터링
느린 검색 성능
- 대규모 컬렉션에는 인덱스 최적화가 필요할 수 있습니다.
- n_results 더 적게 사용하는 것을 고려하세요
- 시스템 리소스 사용량 확인

디버그 모드

디버그 모드에서 서버를 실행합니다.

mcp-server-chroma --log-level DEBUG

도움 받기

ChromaDB 문서 확인
GitHub에 이슈를 열어보세요
MCP 커뮤니티 토론에 참여하세요

개발

테스트 실행

테스트 모음을 실행합니다.

pytest -v

적용 범위:

pytest --cov=chroma tests/

디버깅

디버깅을 위해 MCP Inspector를 사용하세요.

# Install the inspector
npm install -g @modelcontextprotocol/inspector

# Run the server with inspector
mcp-inspector uv --directory /path/to/mcp-server-chroma run mcp-server-chroma

검사관은 다음을 제공합니다.

실시간 요청/응답 모니터링
도구 테스트 인터페이스
성과 지표
오류 추적

오류 처리

서버는 일반적인 시나리오에 대한 자세한 오류 메시지를 제공합니다.

잘못된 컬렉션 이름 또는 ID
누락되었거나 잘못된 문서
데이터베이스 연결 문제
잘못된 검색 매개변수입니다
인증/권한 부여 실패

보안 고려 사항

모든 매개변수에 대한 입력 검증
구성 가능한 액세스 제어
파일 경로의 안전한 처리
주입 공격에 대한 보호
속도 제한 지원
보안 오류 메시지

구성

데이터베이스 위치

사용자 정의 데이터베이스 경로 설정:

mcp-server-chroma --db-path /path/to/db

기본값: 서버 디렉토리의 .chroma

환경 변수

CHROMA_DB_PATH : 데이터베이스 위치 재정의
CHROMA_LOG_LEVEL : 로깅 세부 정보 설정(기본값: INFO)
CHROMA_MAX_CONNECTIONS : 데이터베이스 연결 풀 크기(기본값: 10)

기여하다

저장소를 포크하세요
기능 브랜치 생성
변경 사항을 만드세요
새로운 기능에 대한 테스트 추가
풀 리퀘스트 제출

자세한 내용은 기여 지침을 읽어보세요.

특허

MIT 라이센스

본 소프트웨어 및 관련 문서 파일(이하 "소프트웨어")의 사본을 취득한 모든 사람에게 소프트웨어를 제한 없이 거래할 수 있는 권한을 무상으로 부여합니다. 여기에는 소프트웨어 사본을 사용, 복사, 수정, 병합, 게시, 배포, 하위 라이선스 및/또는 판매할 수 있는 권한이 포함되나 이에 국한되지 않으며, 소프트웨어가 제공된 사람에게도 이러한 권한을 부여합니다. 단, 다음 조건에 따라야 합니다.

본 소프트웨어는 상품성, 특정 목적 적합성 및 비침해에 대한 보증을 포함하되 이에 국한되지 않는 명시적 또는 묵시적 보증 없이 "있는 그대로" 제공됩니다. 어떠한 경우에도 저작자 또는 저작권자는 본 소프트웨어 또는 본 소프트웨어의 사용 또는 기타 거래와 관련하여 발생하는 계약, 불법 행위 또는 기타 소송을 포함한 모든 청구, 손해 또는 기타 책임에 대해 책임을 지지 않습니다.

Chroma MCP Server

크로마 MCP 서버

특징

요구 사항

빠른 시작

건축학

데이터 흐름

구성 요소

컬렉션 및 문서

도구

컬렉션 관리

문서 작업

설치

필수 조건

설정

Claude 데스크톱 통합

사용 예

컬렉션 관리

문서 작업

유사성 점수 이해

문제 해결

일반적인 문제

디버그 모드

도움 받기

개발

테스트 실행

디버깅

오류 처리

보안 고려 사항

구성

데이터베이스 위치

환경 변수

기여하다

특허

Related Resources

Appeared in Searches