Database MCP Server

PostgreSQL 데이터베이스를 read-only로 연결하여 자연어로 데이터를 조회하고 분석할 수 있는 MCP(Model Context Protocol) 서버입니다.

✨ 기능

• 🔍 Read-Only SQL 쿼리 실행: SELECT 문을 통한 안전한 데이터 조회
• 📊 스키마 탐색: 테이블 목록 조회 및 상세 정보 확인
• 💬 자연어 분석: 자연어로 데이터 질문하고 분석
• 🔒 안전성: SELECT, WITH, SHOW, DESCRIBE 문만 허용하여 데이터 변경 방지
• 📚 스키마 메타데이터: 테이블 용도, 주요 컬럼, 자주 쓰는 쿼리를 미리 정의하여 Claude가 더 정확한 쿼리 생성

🚀 빠른 시작

한 줄 명령어로 설치

npx somoon-db-mcp setup

대화형으로 다음을 입력:

1. 데이터베이스 정보:
   • Host
   • Port (기본값: 5432)
   • Database Name
   • User (readonly 권장)
   • Password
   • SSL (y/n)
2. 설정 저장 위치:
   • 1: 현재 디렉토리 (프로젝트별)
   • 2: 홈 디렉토리 (전역)

완료! 🎉

📦 설치 방법

방법 1: npx 사용 (권장)

토큰 설정 없이 바로 실행:

npx somoon-db-mcp setup

방법 2: 글로벌 설치

npm install -g somoon-db-mcp
somoon-db-mcp setup

🔧 Claude Code에서 사용

자동 설정 (권장)

npx somoon-db-mcp setup

setup 실행 후:

1. Claude Code 재시작 또는 /mcp 실행
2. "데이터베이스 테이블 목록 보여줘" 같은 질문 시작!

수동 설정

프로젝트 루트 또는 홈 디렉토리에 .mcp.json 생성:

{
  "mcpServers": {
    "somoon-db": {
      "command": "npx",
      "args": ["-y", "somoon-db-mcp@latest"],
      "env": {
        "DB_HOST": "your-db-host.com",
        "DB_PORT": "5432",
        "DB_NAME": "your_database",
        "DB_USER": "readonly_user",
        "DB_PASSWORD": "your_password",
        "DB_SSL": "true"
      }
    }
  }
}

환경 변수 사용 (보안 권장)

비밀번호를 파일에 저장하지 않으려면:

~/.bashrc 또는 ~/.zshrc에 추가:

export DB_HOST="your-db-host.com"
export DB_PORT="5432"
export DB_NAME="your_database"
export DB_USER="readonly_user"
export DB_PASSWORD="your_password"
export DB_SSL="true"

.mcp.json:

{
  "mcpServers": {
    "somoon-db": {
      "command": "npx",
      "args": ["-y", "somoon-db-mcp@latest"],
      "env": {
        "DB_HOST": "${DB_HOST}",
        "DB_PORT": "${DB_PORT}",
        "DB_NAME": "${DB_NAME}",
        "DB_USER": "${DB_USER}",
        "DB_PASSWORD": "${DB_PASSWORD}",
        "DB_SSL": "${DB_SSL}"
      }
    }
  }
}

🎯 제공 Tools

1. execute_query

SQL SELECT 쿼리를 실행합니다.

Parameters:

• query (string, required): SQL SELECT 쿼리
• params (array, optional): Prepared statement 파라미터

Example:

SELECT * FROM users WHERE created_at > $1 LIMIT 10

2. list_tables

데이터베이스의 모든 테이블 목록을 조회합니다.

Parameters:

• schema (string, optional): 스키마 이름 (기본값: public)

3. describe_table

특정 테이블의 상세 정보를 조회합니다.

Parameters:

• tableName (string, required): 테이블 이름
• schema (string, optional): 스키마 이름 (기본값: public)

4. analyze_data

자연어 설명을 기반으로 데이터 분석을 지원합니다.

Parameters:

• description (string, required): 원하는 데이터에 대한 자연어 설명
• context (string, optional): 추가 컨텍스트나 제약조건

💡 사용 예시

Claude Code에서 자연어로 질문하세요:

"데이터베이스에 어떤 테이블들이 있어?"
"users 테이블의 구조를 알려줘"
"최근 7일간 가입한 사용자 수를 알려줘"
"가장 많이 팔린 상품 10개를 보여줘"
"월별 매출 추이를 분석해줘"

🔐 보안 설정 (필수)

Read-Only 사용자 생성

데이터베이스에 read-only 권한만 가진 사용자를 생성하는 것을 강력히 권장합니다:

-- PostgreSQL 예시
CREATE USER readonly_user WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE your_database TO readonly_user;
GRANT USAGE ON SCHEMA public TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO readonly_user;

보안 체크리스트

• ✅ Read-Only 권한: SELECT 권한만 가진 사용자 사용
• ✅ 환경 변수: 비밀번호를 환경 변수로 관리
• ✅ SSL 연결: 프로덕션 환경에서 SSL 사용
• ✅ 쿼리 제한: SELECT, WITH, SHOW, DESCRIBE 문만 허용
• ✅ VPN/방화벽: 회사 네트워크 내에서만 DB 접근

📚 스키마 메타데이터 커스터마이징

데이터베이스의 테이블 구조와 용도를 schema-metadata.json 파일에 정의하면, Claude가 더 정확하고 효율적인 쿼리를 생성할 수 있습니다.

메타데이터 파일 구조

{
  "tables": {
    "테이블이름": {
      "description": "테이블 설명",
      "purpose": "테이블의 용도",
      "primaryKey": "기본키 컬럼명",
      "commonQueries": [
        "자주 사용하는 질문 예시"
      ],
      "importantColumns": {
        "컬럼명": "컬럼 설명"
      },
      "relationships": {
        "연관테이블": "조인 조건"
      }
    }
  },
  "queryExamples": {
    "예시이름": {
      "description": "쿼리 설명",
      "sql": "실제 SQL 쿼리"
    }
  }
}

메타데이터 작성 팁

1. 주요 테이블 우선: 자주 사용하는 테이블부터 작성
2. 명확한 설명: 각 테이블과 컬럼의 비즈니스 용도를 명확히 작성
3. 실제 쿼리 예시: 자주 사용하는 쿼리 패턴을 예시로 추가
4. 관계 정의: 테이블 간 조인 조건을 명시하여 복잡한 쿼리 지원

메타데이터 효과

• ✅ Claude가 테이블 용도를 이해하고 적절한 테이블 선택
• ✅ 중요한 컬럼을 우선적으로 사용
• ✅ 자주 사용하는 쿼리 패턴을 빠르게 생성
• ✅ 테이블 간 관계를 고려한 JOIN 쿼리 작성

🛠️ 개발

프로젝트 구조

somoon-db-mcp/
├── src/
│   ├── index.ts        # MCP 서버 메인 로직
│   ├── database.ts     # 데이터베이스 서비스
│   └── setup.ts        # 대화형 설정 도구
├── build/              # 빌드 결과물
├── package.json
├── tsconfig.json
└── README.md

로컬 개발

# 의존성 설치
npm install

# 빌드
npm run build

# 개발 모드 (watch)
npm run watch

배포

# 버전 업데이트
npm version patch  # 또는 minor, major

# npm 배포
npm publish

# Git 푸시
git push origin main --tags

🐛 문제 해결

"Cannot find package" 오류

npm이 패키지를 찾을 수 없는 경우:

# npm 캐시 삭제
npm cache clean --force

# 다시 시도
npx somoon-db-mcp setup

DB 연결 오류

1. VPN 연결 확인
2. DB 호스트/포트 확인
3. DB 사용자 권한 확인
4. 방화벽 설정 확인

설정 다시 하기

# 같은 명령어 다시 실행
npx somoon-db-mcp setup

기존 설정을 업데이트합니다.

📄 라이선스

MIT License