카우치베이스 MCP 서버

LLM이 Couchbase 클러스터와 직접 상호 작용할 수 있도록 하는 Couchbase의 MCP 서버 구현입니다.

특징

지정된 버킷의 모든 범위 및 컬렉션 목록을 가져옵니다.
컬렉션의 구조를 얻으세요
지정된 범위 및 컬렉션에서 ID로 문서 가져오기
지정된 범위 및 컬렉션에 ID로 문서를 업서트합니다.
지정된 범위 및 컬렉션에서 ID로 문서 삭제
지정된 범위에서 SQL++ 쿼리 실행
- MCP 서버에는 기본적으로 true로 설정된 READ_ONLY_QUERY_MODE 옵션이 있는데, 이 옵션은 데이터 또는 기본 컬렉션 구조를 변경하는 SQL++ 쿼리 실행을 비활성화합니다. 단, 문서는 ID로 계속 업데이트할 수 있습니다.

필수 조건

Python 3.10 이상.
실행 중인 Couchbase 클러스터입니다. 시작하는 가장 쉬운 방법은 Couchbase 서버의 완전 관리형 버전인 Capella 무료 티어를 사용하는 것입니다. 지침 에 따라 샘플 데이터세트 중 하나를 가져오거나 직접 가져올 수 있습니다.
서버를 실행하기 위해 uv가 설치되었습니다.
Claude Desktop과 같은 MCP 클라이언트를 설치하여 서버를 Claude에 연결합니다. Claude Desktop과 Cursor에 대한 지침이 제공됩니다. 다른 MCP 클라이언트도 사용할 수 있습니다.

구성

저장소를 로컬 컴퓨터에 복제합니다.

지엑스피1

MCP 클라이언트를 위한 서버 구성

이는 Claude Desktop, Cursor, Windsurf Editor와 같은 MCP 클라이언트의 일반적인 구성입니다.

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_BUCKET_NAME": "bucket_name"
      }
    }
  }
}

환경 변수를 사용하여 서버를 구성할 수 있습니다. 지원되는 변수는 다음과 같습니다.

CB_CONNECTION_STRING : Couchbase 클러스터에 대한 연결 문자열
CB_USERNAME : 버킷에 접속할 수 있는 사용자 이름
CB_PASSWORD : 연결할 사용자 이름의 비밀번호
CB_BUCKET_NAME : 서버가 액세스할 버킷의 이름
READ_ONLY_QUERY_MODE : 데이터 수정을 허용하는 SQL++ 쿼리의 허용 여부를 설정합니다. 기본적으로 True로 설정됩니다.
path/to/cloned/repo/mcp-server-couchbase/ 로컬 컴퓨터의 복제된 저장소 경로여야 합니다. 맨 마지막에 슬래시를 넣는 것을 잊지 마세요!

참고: 클라이언트에서 다른 MCP 서버를 사용 중인 경우 기존 mcpServers 개체에 추가할 수 있습니다.

클로드 데스크탑

Claude Desktop MCP 클라이언트와 함께 Couchbase MCP 서버를 사용하려면 아래 단계를 따르세요.

이제 구성 파일을 편집하여 Claude Desktop에 MCP 서버를 추가할 수 있습니다. 자세한 내용은 MCP 빠른 시작 가이드를 참조하세요.
- Mac에서는 구성 파일이 ~/Library/Application Support/Claude/claude_desktop_config.json 에 있습니다.
- Windows에서는 구성 파일이 %APPDATA%\Claude\claude_desktop_config.json 에 있습니다.
구성 파일을 열고 mcpServers 섹션에 구성을 추가합니다.
변경 사항을 적용하려면 Claude Desktop을 다시 시작하세요.
이제 Claude Desktop의 서버를 사용하여 자연어를 사용하여 Couchbase 클러스터에서 쿼리를 실행하고 문서에 대한 CRUD 작업을 수행할 수 있습니다.

클로드 데스크톱 로그

Claude Desktop의 로그는 다음 위치에서 찾을 수 있습니다.

MacOS: ~/라이브러리/로그/클로드
윈도우: %APPDATA%\Claude\Logs

로그는 연결 문제나 MCP 서버 구성 관련 기타 문제를 진단하는 데 사용할 수 있습니다. 자세한 내용은 공식 문서를 참조하세요.

커서

Cursor와 함께 Couchbase MCP 서버를 사용하려면 아래 단계를 따르세요.

컴퓨터에 커서를 설치하세요.
커서에서 커서 > 커서 설정 > MCP > 새 글로벌 MCP 서버 추가로 이동하세요. 커서에서 MCP 서버 구성을 설정하는 방법도 참조하세요.
동일한 구성을 지정하세요. mcpServers라는 상위 키 아래에 서버 구성을 추가해야 할 수도 있습니다.
구성을 저장합니다.
MCP 서버 목록에 Couchbase가 추가된 서버로 표시됩니다. 서버가 활성화되어 있는지 확인하려면 새로 고침하세요.
이제 Cursor에서 Couchbase MCP 서버를 사용하여 자연어로 Couchbase 클러스터를 쿼리하고 문서에 대한 CRUD 작업을 수행할 수 있습니다.

Cursor와 MCP 통합에 대한 자세한 내용은 공식 Cursor MCP 문서를 참조하세요.

커서 로그

커서 하단 패널에서 "출력"을 클릭하고 드롭다운 메뉴에서 "커서 MCP"를 선택하면 서버 로그를 볼 수 있습니다. 이를 통해 연결 문제나 MCP 서버 구성 관련 문제를 진단하는 데 도움이 될 수 있습니다.

윈드서핑 편집자

Windsurf Editor 와 함께 Couchbase MCP 서버를 사용하려면 아래 단계를 따르세요.

컴퓨터에 Windsurf Editor를 설치하세요.
Windsurf 편집기에서 명령 팔레트 > Windsurf MCP 구성 패널 또는 Windsurf - 설정 > 고급 > 캐스케이드 > 모델 컨텍스트 프로토콜(MCP) 서버로 이동합니다. 구성에 대한 자세한 내용은 공식 문서를 참조하세요.
'서버 추가'를 클릭한 다음 '사용자 지정 서버 추가'를 클릭합니다. 편집기에서 열리는 구성에서 위에서 설정한 Couchbase MCP 서버 구성을 추가합니다.
구성을 저장합니다.
고급 설정의 MCP 서버 목록에 Couchbase가 추가된 서버로 표시됩니다. 서버가 활성화되어 있는지 확인하려면 새로 고침하세요.
이제 Windsurf Editor에서 Couchbase MCP 서버를 사용하여 자연어로 Couchbase 클러스터를 쿼리하고 문서에 대한 CRUD 작업을 수행할 수 있습니다.

Windsurf Editor와 MCP 통합에 대한 자세한 내용은 공식 Windsurf MCP 문서를 참조하세요.

SSE 서버 모드

MCP 서버를 SSE(Server-Sent Events) 전송 모드로 실행하는 옵션이 있습니다.

용법

기본적으로 MCP 서버는 포트 8080에서 실행되지만 FASTMCP_PORT 환경 변수를 사용하여 구성할 수 있습니다.

uv run src/mcp_server.py --connection-string='<couchbase_connection_string>' --username='<database_username>' --password='<database_password>' --bucket-name='<couchbase_bucket_to_use>' --read-only-query-mode=true --transport=sse

서버는 http://localhost:8080/sse 에서 사용할 수 있습니다. SSE 전송 모드를 지원하는 MCP 클라이언트에서 사용할 수 있습니다.

도커 이미지

MCP 서버는 Docker 컨테이너로도 빌드하고 실행할 수 있습니다. 미리 빌드된 이미지는 DockerHub 에서 찾을 수 있습니다.

docker built -t mcp/couchbase .

달리기

MCP 서버는 Couchbase 설정을 구성하는 데 사용되는 환경 변수와 함께 실행될 수 있습니다. 환경 변수는 구성 섹션 에서 설명한 것과 동일합니다.

docker run -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_BUCKET_NAME='<bucket_name>' \
  -e MCP_TRANSPORT='stdio/sse' \
  -e READ_ONLY_QUERY_MODE="true/false" \
  mcp/couchbase

LLM과 관련된 위험

대규모 언어 모델이나 이와 유사한 기술을 사용하면 부정확하거나 유해한 출력이 나올 가능성을 포함한 위험이 따릅니다.
Couchbase는 이러한 출력의 품질이나 정확성을 검토하거나 평가하지 않으며, 이러한 출력은 Couchbase의 견해를 반영하지 않을 수 있습니다.
대규모 언어 모델 및 관련 기술을 사용할지 여부를 결정하고, 동일한 기술의 사용을 규정하는 모든 라이선스 조건, 이용 약관 및 조직의 정책을 준수하는 것은 전적으로 귀하의 책임입니다.

관리형 MCP 서버

Couchbase MCP 서버는 Smithery.ai 를 통해 에이전트 애플리케이션에서 관리되는 서버로도 사용할 수 있습니다.

문제 해결 팁

구성에서 MCP 서버 저장소 경로가 올바른지 확인하세요.
Couchbase 연결 문자열, 데이터베이스 사용자 이름, 비밀번호 및 버킷 이름이 올바른지 확인하세요.
Couchbase Capella를 사용하는 경우 MCP 서버가 실행 중인 컴퓨터에서 클러스터에 액세스할 수 있는지 확인하세요.
데이터베이스 사용자에게 지정된 버킷에 액세스할 수 있는 적절한 권한이 있는지 확인하세요.
uv 패키지 관리자가 제대로 설치되고 접근 가능한지 확인하세요. 설정 파일의 command 필드에 uv의 절대 경로를 입력해야 할 수도 있습니다.
MCP 서버 관련 문제를 나타낼 수 있는 오류나 경고가 있는지 로그를 확인하세요. 서버 로그는 mcp-server-couchbase.log 라는 이름으로 저장됩니다.

📢 지원 정책

이 프로젝트에 관심을 가져주셔서 진심으로 감사드립니다!
이 프로젝트는 커뮤니티에서 유지 관리되는 프로젝트이므로 당사 지원팀에서 공식적으로 지원하지 않습니다 .

도움이 필요하거나 버그를 발견했거나 개선에 기여하고 싶다면 바로 여기, GitHub 이슈를 여는 것이 가장 좋습니다.
당사 지원 포털에서는 이 프로젝트와 관련된 요청을 지원할 수 없으므로, 모든 문의는 GitHub 내에서만 접수해 주시기 바랍니다.

여러분의 협력 덕분에 우리 모두가 함께 앞으로 나아갈 수 있게 되었습니다. 감사합니다!

Couchbase MCP Server

Integrations