AI导哈

PostgreSQL最佳实践分析工具

一款自动分析PostgreSQL操作最佳实践的MCP服务器，提供实时性能优化、安全检查和索引建议。适用于数据库开发与运维场景。

  • by KBY-CL
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 KBY-CL/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개+ 규칙 파일

자동 분석 항목

도구별 분석

도구 자동 분석 내용
connect_db pg_stat_statements 활성화, log_lock_waits 설정
query SELECT *, OFFSET 페이지네이션, 인덱스 누락, 복합인덱스, JSONB GIN
execute 배치 INSERT, UPSERT, WHERE 없는 UPDATE/DELETE, SKIP LOCKED
describe_table PK 전략, 데이터타입, NOT NULL, JSONB GIN, RLS, FK 인덱스, 소문자 식별자
list_tables FK 인덱스 누락, RLS 미적용 테이블

분석 레벨

레벨 의미
CRITICAL 즉시 조치 필요 (보안, 데이터 손실 위험)
WARNING 성능 문제 가능성 높음
SUGGESTION 개선하면 좋은 사항
INFO 참고 정보

Best Practices 규칙 카테고리

우선순위 카테고리 영향도 규칙 수
1 Query Performance CRITICAL 5
2 Connection Management CRITICAL 4
3 Security & RLS CRITICAL 3
4 Schema Design HIGH 6
5 Concurrency & Locking MEDIUM-HIGH 4
6 Data Access Patterns MEDIUM 4
7 Monitoring & Diagnostics LOW-MEDIUM 3
8 Advanced Features LOW 2

아키텍처

┌──────────────┐    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"
  }
}

문제 해결

증상 해결 방법
"Database not connected" .mcp.json DB 접속정보 확인, 네트워크/VPN 확인
MCP 서버 인식 안 됨 mcp-server/dist/index.js 존재 확인, 경로를 절대경로로 변경
빌드 실패 Node.js 18+ 확인, cd mcp-server && npm install && npm run build
분석 결과 안 나옴 Claude Code 재시작 (Ctrl+Shift+P → Reload Window)

라이선스

MIT

相关 MCP