PostgreSQL AI Explorer

v1.2.0 | MCP SDK 1.26 · psycopg 3 · Streamlit

PostgreSQL 데이터베이스를 MCP(Model Context Protocol) 로 연결하여,
AI와 대화하며 자연어로 데이터를 탐색하고 시각화하는 프로젝트입니다.

---

🚀 주요 기능

기능	설명
자연어 → SQL 변환	복잡한 SQL 문법 없이 질문으로 데이터 조회
MCP 프로토콜 지원	Claude Desktop(stdio) 및 기타 MCP 클라이언트(SSE)와 연동
Streamlit Web UI	채팅 인터페이스 + Plotly 차트 자동 생성
실전형 데모 데이터	한국형 인사관리 데이터셋 자동 생성 스크립트 포함

---

🛠️ 설치 및 설정

1. 필수 요구사항

• Python 3.10 이상
• PostgreSQL 데이터베이스 (Local 또는 Docker)
• Poetry (패키지 관리자)

2. 설치

# 의존성 설치
poetry install

3. 환경 설정 (.env)

프로젝트 루트에 .env 파일을 생성하고 데이터베이스 정보를 입력하세요.

# PostgreSQL 접속 정보
DB_HOST=localhost
DB_PORT=5432
DB_NAME=postgres
DB_USER=postgres
DB_PASSWORD=your_password

# (선택) AI API 키 — Streamlit 웹 UI에서 자연어→SQL 변환 시 필요
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

---

🏃‍♂️ 실행 방법

1. 데이터베이스 초기화 (데모 데이터 생성)

실습용 인사관리 테이블을 생성하고 약 50명의 가상 사원 정보를 채웁니다.

poetry run python scripts/setup_demo_data.py

2-A. Claude Desktop 연동 (stdio 모드, 기본)

Claude Desktop의 설정 파일 %APPDATA%\Claude\claude_desktop_config.json 에 아래 내용을 추가합니다.

{
  "mcpServers": {
    "postgresql": {
      "command": "<프로젝트경로>\\.venv\\Scripts\\python.exe",
      "args": ["-m", "src.server"],
      "env": {
        "PYTHONPATH": "<프로젝트경로>"
      }
    }
  }
}

설정 후 Claude Desktop을 재시작하면 자동으로 MCP 서버가 연결됩니다.

2-B. Streamlit 웹 UI (SSE 모드)

SSE 백엔드 서버와 Streamlit 프론트엔드를 각각 실행합니다.

# 터미널 1: MCP 서버 (SSE 모드)
poetry run python -m src.server --sse

# 터미널 2: Streamlit 앱
poetry run streamlit run src/streamlit_app.py

---

🧪 테스트 쿼리 예시

• "개발팀의 평균 연봉은 얼마인가요?"
• "근속 3년 이상인 직원 중 급여 상위 5명 보여줘"
• "부서별 남녀 성비를 파이차트로 그려줘"
• "부서별 인원수 Top 5과 평균 근속연수를 함께 보여줘"
• "올해 입사한 신입사원 명단"

더 많은 예시는 query.md 를 참고하세요.

---

📁 프로젝트 구조

PostgreSQL_MCP/
├── src/                       # 핵심 패키지 (서버 + 설정 + 웹 UI)
│   ├── __init__.py            #   패키지 메타 (버전 정보)
│   ├── server.py              #   MCP 서버 핵심 로직 (stdio + SSE 전송)
│   ├── config.py              #   통합 설정 (DB, MCP, AI 프롬프트 등)
│   └── streamlit_app.py       #   Streamlit 웹 UI (채팅 + 차트)
├── scripts/
│   └── setup_demo_data.py     #   데모 데이터(인사관리) 생성 스크립트
├── docs/
│   └── ARCHITECTURE.md        #   시스템 아키텍처 문서
├── query.md                   # 추천 자연어 쿼리 예시 모음
├── pyproject.toml             # Poetry 의존성 관리
├── claude_desktop_config.json # Claude Desktop 설정 예시
└── archive/                   # 이전 버전 / 디버깅용 파일 보관