YugabyteDB를 이용한 Claude Desktop MCP 서버 설치

 

YugabyteDB를 이용한  Claude Desktop MCP 서버 설치

MCP란?

MCP(Model Context Protocol)는 대규모 언어 모델(LLM)이 일관되고 표준화된 방식으로 기존 엔터프라이즈 서비스와 상호 작용할 수 있도록 하는 새로운 표준입니다. 
즉) MCP 서버는 AI가 외부 시스템과 연결되도록 커스텀 API 통합 할 수 있는 표준 인터페이스 입니다.

 MCP 서버로 LLM(예: Claude)이 자연어로 YugabyteDB에 직접 접근하고 데이터를 분석할 수 있도록 해주는 Python 기반 경량 서버를 구성 할 수 있습니다 yugabyte.com.

https://modelcontextprotocol.io/docs/getting-started/intro

 

 

⚙️ MCP의 필요성

• 개발자 : MCP는 AI 애플리케이션이나 에이전트를 구축하거나 통합할 때 개발 시간과 복잡성을 줄여줍니다.
• AI 애플리케이션 또는 에이전트 : MCP는 데이터 소스, 도구 및 앱 생태계에 대한 액세스를 제공하여 기능을 강화하고 최종 사용자 경험을 개선합니다.
• 최종 사용자 : MCP는 필요할 때 데이터에 액세스하고 사용자를 대신하여 조치를 취할 수 있는 더욱 유능한 AI 애플리케이션이나 에이전트를 제공합니다.

 

🧠 MCP 서버의 장점

• 표준화된 MCP 프로토콜로 AI 서비스 간의 확장성과 호환성 제공
• LLM이 실시간 데이터에 접근 가능(RAG)
• 안전한 쿼리 실행으로 프로덕션 데이터 보호
• Claude, Cursor, Windsurf 등 다양한 툴과 호환  인터페이스 제공

 

 

---

🔧 MCP의 핵심 역할

🔗 연결자 역할	AI 모델과 데이터베이스, 파일 서버, 이메일 시스템 등 외부 서비스 간의 연결을 표준화
🧰 도구 탐색 및 호출	MCP 서버가 제공하는 기능(API)을 LLM이 이해하고 사용할 수 있도록 구조화
🛡️ 보안성과 일관성 확보	안전한 방식으로 외부 시스템에 접근하며, 다양한 앱에서 재사용 가능
📦 확장성과 호환성	LangChain, Claude, Cursor 등 다양한 프레임워크와 호환되며, 개발 효율성 향상
🧠 맥락 인지 능력 향상	AI가 실시간으로 컨텍스트(예: 최신 데이터, 사용자 정보 등)를 받아들여 더 똑똑한 응답 생성 가능

 

MCP의 아키텍처

• MCP 호스트 : 하나 이상의 MCP 클라이언트를 조정하고 관리하는 AI 애플리케이션, 하나이상의 MCP서버을 연결 합니다.
• MCP 서버 : MCP 클라이언트에 컨텍스트 데이터를 제공하는 프로그램입니다. 하나의 MCP 클라이언트를 생성하여 수행합니다.
• MCP 클라이언트 : MCP 서버와의 1:1 연결을 유지하고 MCP 호스트가 사용할 수 있도록 MCP 서버에서 컨텍스트를 가져오는 구성 요소입니다.

MCP는 클라이언트 - 서버  아키텍처를 따르며 다음과 같은 구성을 갖추고 있습니다.

 

 

MCP의 레이어

MCP는 두 개의 계층으로 구성됩니다.

• 데이터 계층 : 메시지 구조와 의미를 정의하는 JSON-RPC 2.0 기반 교환 프로토콜을 구현합니다. 수명 주기 관리 및 도구, 서버 기능 (작업도구, 리소스, 상호작용,프롬프트, 알림등 핵심 기본요소) , 클라이언트 기능 (클라이언트-서버 통신,  JSON-RPC 기반 프로토콜 ) , 유틸리티 기능 ( 실시간 업데이트,장기 실행 작업, 추적등) 등 데이터 프로토콜을 정의합니다.
• 전송 계층 : 표준 입출력 전송 , 스트리밍 가능한 HTTP 전송 등 클라이언트와 서버 간 데이터 교환을 가능하게 하는 통신 메커니즘과 채널을 정의합니다. 여기에는 전송 관련 연결 설정, 메시지 프레이밍, 권한 부여가 포함됩니다.

 

 

🧪 활용 시나리오

1. Claude 같은 LLM이 YugabyteDB MCP 서버를 통해 데이터베이스에 접속
2. 자연어로 “지난달 매출 요약해줘”라고 요청
3. Claude는 MCP를 통해 안전한 SQL 쿼리를 실행하고, 결과를 요약해서 보여줌
4. 사용자는 SQL을 몰라도 AI를 통해 데이터 분석 가능

 

 

 

---

📦 1. 사전 준비 사항

• YugabyteDB 인스턴스 (로컬 또는 원격) : https://docs.yugabyte.com/preview/quick-start/linux/
• Python 3.10 이상
• uv 패키지 관리자 (Python 의존성 관리용) : pip install uv; uv sync
• Claude Desktop 앱 (LLM 인터페이스용) : https://claude.ai/download

---

# install YugaByteDB (Linux)

wget https://software.yugabyte.com/releases/2.25.2.0/yugabyte-2.25.2.0-b359-linux-x86_64.tar.gz
tar xvfz yugabyte-2.25.2.0-b359-linux-x86_64.tar.gz && cd yugabyte-2.25.2.0/


./bin/post_install.sh

./bin/yugabyted start --advertise_address 127.0.0.1

 

 

🛠️ 2. MCP 서버 다운로드 및 설치

# GitHub에서 MCP 서버 클론
git clone https://github.com/yugabyte/yugabytedb-mcp-server.git

# 디렉토리 이동
cd yugabytedb-mcp-server

# 의존성 설치
uv sync

uv는 Python 프로젝트의 패키지 관리를 위한 도구입니다. 설치가 안 되어 있다면 pip install uv로 먼저 설치하세요.

 

 

---

⚙️ 3. Claude와 MCP 서버 연결 설정

Claude Desktop 앱에서 다음 설정을 추가합니다:

1. 경로: Settings → Developer → Edit Config
2. claude_config.json에 다음 항목 추가:

{
  "mcpServers": {
    "yugabytedb-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/cloned/yugabytedb-mcp-server/",
        "run",
        "src/server.py"
      ],
      "env": {
        "YUGABYTEDB_URL": "dbname=northwind host=localhost port=5433 user=yugabyte password=yugabyte load_balance=true"
      }
    }
  }
}

YUGABYTEDB_URL은 실제 데이터베이스 접속 정보입니다. Northwind 샘플 데이터셋이 미리 로드된 상태를 가정합니다.

1. Claude 앱 재시작 후 로그 확인:
   • macOS: ~/Library/Logs/Claude
   • Windows: %APPDATA%\Claude\Logs

 

---

🧪 4. 테스트 프롬프트 예시

 

✅ 프롬프트 1: 데이터베이스 요약

Summarize the database you are connected to.

Claude는:

• 모든 테이블 목록과 스키마, 행 수를 요약
• 자연어로 설명

 

✅ 프롬프트 2: 대시보드 생성

Build a dashboard with 3 visualizations:
- Monthly sales trend
- Top 10 customers by revenue
- Sales grouped by customer country

Claude는:

• 안전한 읽기 전용 SQL 실행
• 결과를 집계 및 시각화
• 인터랙티브 대시보드 생성

SQL을 직접 작성하지 않아도 자연어로 데이터 분석이 가능합니다!

---