custom postgres MCP

PostgreSQL Best Practices MCP Server

Claude Code에서 PostgreSQL 작업 시 Best Practices를 자동으로 분석해주는 커스텀 MCP 서버입니다.

쿼리 실행, 스키마 조회, 데이터 변경 등 모든 DB 작업에 대해 인덱스 누락, 보안 취약점, 성능 개선 사항을 실시간으로 경고합니다.

주요 기능

• 6개 MCP 도구 — connect_db, query, execute, describe_table, list_tables, list_schemas
• Best Practices 자동 분석 — 쿼리/스키마/DML 실행 시 30개+ 규칙 기반 분석 결과 자동 포함
• postgresql-best-practices Skill — 8개 카테고리 규칙 파일 (Claude가 참조하는 문서)

분석 예시

⚠️ [WARNING] query-missing-indexes
   WHERE/JOIN 조건의 컬럼 [modelname]에 인덱스가 없습니다.
   → CREATE INDEX ON pmis_ai.tsst_ai_logs (modelname); 를 고려하세요.

🔴 [CRITICAL] security-rls-basics
   사용자/테넌트 식별 컬럼이 있지만 RLS가 비활성화되어 있습니다.
   → ALTER TABLE ... ENABLE ROW LEVEL SECURITY; 후 정책을 추가하세요.

💡 [SUGGESTION] data-batch-inserts
   단일 행 INSERT를 감지했습니다.
   → VALUES (...), (...) 형태의 배치 INSERT로 10-50배 성능을 높이세요.

빠른 시작

1. 클론 및 설치

git clone https://github.com/KBY-CL/custom_postgres_mcp.git
cd custom_postgres_mcp
bash setup.sh

또는 수동 설치:

cd mcp-server
npm install
npm run build

2. DB 접속정보 설정

.mcp.json.template을 .mcp.json으로 복사한 후 접속정보를 수정합니다.

cp .mcp.json.template .mcp.json

.mcp.json 수정:

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/mcp-server/dist/index.js"],
      "env": {
        "PG_HOST": "your-host.example.com",
        "PG_PORT": "5432",
        "PG_USER": "your-user",
        "PG_PASSWORD": "your-password",
        "PG_DATABASE": "your-database",
        "PGSSLMODE": "require",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

.mcp.json은 .gitignore에 포함되어 있어 DB 비밀번호가 git에 올라가지 않습니다.

3. Claude Code 재시작

Ctrl+Shift+P → Developer: Reload Window

4. 사용

Claude Code에서 자연어로 요청하면 됩니다:

"users 테이블 스키마 검토해줘"
"companyid별 토큰 사용량 조회 쿼리 작성해줘"
"테이블 성능 상태 진단해줘"

프로젝트 구조

.
├── .mcp.json.template          # DB 접속정보 템플릿
├── CLAUDE.md                   # Claude 자동 참조 지시
├── SETUP-GUIDE.md              # 상세 설치/사용 가이드
├── ROADMAP.md                  # AI 자동화 로드맵
├── setup.sh                    # 자동 설치 스크립트
│
├── mcp-server/                 # 커스텀 MCP 서버
│   ├── src/
│   │   ├── index.ts            # MCP 서버 진입점
│   │   ├── db.ts               # PostgreSQL 연결 관리
│   │   ├── types.ts            # 타입 정의
│   │   ├── tools/              # 6개 MCP 도구
│   │   │   ├── connect.ts      # DB 연결 + 설정 점검
│   │   │   ├── query.ts        # SELECT 쿼리 + 분석
│   │   │   ├── execute.ts      # INSERT/UPDATE/DELETE + 분석
│   │   │   ├── describe.ts     # 테이블 구조 + 스키마 분석
│   │   │   └── list.ts         # 스키마/테이블 목록 + FK/RLS 점검
│   │   └── checkers/           # Best Practices 분석 엔진
│   │       ├── query-checker.ts    # SELECT 쿼리 분석
│   │       ├── schema-checker.ts   # 스키마 분석
│   │       └── execute-checker.ts  # DML 분석
│   ├── package.json
│   └── tsconfig.json
│
└── .agents/skills/
    └── postgresql-best-practices/  # Best Practices 규칙 문서
        ├── SKILL.md
        └── references/             # 30개+ 규칙 파일

자동 분석 항목

도구별 분석

분석 레벨

Best Practices 규칙 카테고리

아키텍처

┌──────────────┐    stdio     ┌──────────────────┐    TCP/SSL    ┌──────────┐
│  Claude Code │ ◄──────────► │ MCP 서버 (로컬)   │ ◄───────────► │ PostgreSQL│
│  (VSCode)    │              │ Node.js 프로세스   │              │ (원격 DB) │
└──────────────┘              └──────────────────┘              └──────────┘

• MCP 서버는 로컬에서 Node.js 프로세스로 실행
• Claude Code와 stdin/stdout(stdio)으로 통신
• PostgreSQL DB에는 TCP/SSL로 연결 (직접 원격 또는 로컬 터널링)

로컬 터널링 접속 (SSH Tunnel)

원격 DB에 직접 접속이 불가능한 환경에서는 SSH 터널링을 통해 로컬 포트로 포워딩 후 접속합니다.

┌──────────────┐    stdio     ┌──────────────────┐   localhost    ┌────────────┐   SSH Tunnel   ┌──────────┐
│  Claude Code │ ◄──────────► │ MCP 서버 (로컬)   │ ◄────────────► │ SSH 터널    │ ◄────────────► │ PostgreSQL│
│  (VSCode)    │              │ Node.js 프로세스   │               │ (로컬 포트) │               │ (원격 DB) │
└──────────────┘              └──────────────────┘               └────────────┘               └──────────┘

.mcp.json 설정 시 PG_HOST를 localhost로, PG_PORT를 터널링 포트로 지정합니다.

{
  "env": {
    "PG_HOST": "localhost",
    "PG_PORT": "5432",
    "PG_DATABASE": "postgres",
    "PGSSLMODE": "require",
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}

문제 해결

라이선스

MIT