Postgres MCP Pro (crystaldba) — Claude Code MCP 서버

PostgreSQL용 MCP 서버. 설정 가능한 읽기/쓰기 접근, 인덱스 튜닝·실행계획(EXPLAIN) 분석 등 성능 진단 기능을 제공한다.

Postgres MCP Pro는 crystaldba가 만든 오픈소스(MIT) Model Context Protocol(MCP) 서버로, Claude Code 같은 AI 에이전트를 PostgreSQL 데이터베이스에 연결해 단순 조회를 넘어 성능 진단과 튜닝까지 맡길 수 있게 한다. 단순히 DB 연결을 감싸는 수준이 아니라, 초기 코딩부터 테스트·배포·운영 튜닝·유지보수까지 개발 전 과정을 지원하는 것을 목표로 설계됐다.

핵심 기능은 네 갈래다. 첫째 데이터베이스 헬스 진단 — 인덱스 상태, 커넥션 사용률, 버퍼 캐시, vacuum 상태, 시퀀스 한계, 복제 지연 등을 분석한다. 둘째 인덱스 튜닝 — 워크로드에 맞춰 수많은 인덱스 후보를 탐색해 최적안을 제안한다(가상 인덱스 효과 시뮬레이션 포함). 셋째 쿼리 플랜 검토 — EXPLAIN 실행계획을 읽어 병목을 찾고 최적화 방향을 제시한다. 넷째 스키마 인지형 SQL 생성과 안전 실행 — 스키마를 이해한 컨텍스트 기반 SQL 생성과 함께, 읽기 전용 모드·안전 SQL 파싱 등 설정 가능한 접근 제어를 제공해 개발·운영 환경 모두에서 쓸 수 있다.

따라서 "ORM이 만든 쿼리가 느린데 왜 그런지 모르겠다", "어떤 인덱스를 추가해야 효과가 클지 모르겠다", "운영 DB 상태를 주기적으로 점검하고 싶다" 같은 문제에 잘 맞는다. 대상은 PostgreSQL을 쓰는 백엔드 개발자, 데이터/플랫폼 엔지니어, AI 에이전트로 DB 작업을 자동화하려는 팀이다. stdio와 SSE 두 가지 트랜스포트를 지원해 로컬 클라이언트와 원격 환경 모두에 연결할 수 있고, 설치는 Docker 이미지 또는 Python(pipx/uv) 두 방식 중 선택한다. 연결은 DATABASE_URI 환경변수로 지정하며, 정확한 클라이언트 설정 값은 환경마다 다르므로 공식 문서 확인을 권장한다.

언제 쓰나

PostgreSQL 쿼리·인덱스 성능을 AI 에이전트와 함께 진단·개선하고 싶을 때 적합하다. 느린 ORM/SQL 쿼리의 EXPLAIN 분석, 워크로드 기반 인덱스 후보 탐색, 인덱스·vacuum·커넥션·복제 등 DB 헬스 점검이 핵심 용도다. 개발 중 스키마 인지형 SQL 생성이 필요하거나, 운영 DB에서 읽기 전용 등 접근 제어를 둔 채 안전하게 점검하려는 경우에도 좋다.

설치

docker pull crystaldba/postgres-mcp  (또는 pipx install postgres-mcp). 연결은 DATABASE_URI 환경변수로 지정. 정확한 클라이언트 설정은 공식 문서 참조.

Docker 이미지(crystaldba/postgres-mcp) 또는 Python(pipx/uv) 중 하나로 설치하며, 실행에는 Docker 또는 Python 3.12 이상이 필요하다. DB 연결은 DATABASE_URI 환경변수로 전달하고, 사전에 psql이나 pgAdmin으로 접속 정보가 유효한지 확인하면 좋다. stdio·SSE 트랜스포트를 지원하므로 사용하는 MCP 클라이언트(Claude Desktop/Code 등)에 맞춰 설정 파일을 편집해야 한다. 클라이언트별 정확한 등록 형식과 읽기/쓰기 모드 옵션은 환경마다 달라 공식 문서 확인을 권장한다.

필요 키(직접 발급, 플레이스홀더): DATABASE_URI

보안 주의

DATABASE_URI에는 DB 호스트·사용자·비밀번호가 포함되므로 시크릿으로 취급해 환경변수/시크릿 매니저로만 주입하고 로그·커밋·코드에 노출하지 말아야 한다. 쓰기 모드로 연결하면 에이전트가 INSERT/UPDATE/DELETE·DDL 등 데이터 변경·삭제를 수행할 수 있으니, 운영 DB에는 읽기 전용 모드와 최소 권한 계정 사용을 권장한다. 스키마·데이터 내용이나 EXPLAIN 결과가 LLM에 전달되므로 민감 데이터 노출 범위를 확인하고, 테이블 코멘트·데이터 등 외부 입력에 섞인 프롬프트 인젝션 가능성도 염두에 두고 결과를 검증한다.

자주 묻는 질문

GPT-4.1 같은 LLM API 비용이 추가로 드나요?

Postgres MCP Pro 자체는 오픈소스 MCP 서버라 별도 LLM 과금이 없습니다. 다만 연결한 AI 에이전트(Claude 등)가 스키마·EXPLAIN 결과를 처리하면서 토큰을 소비하므로, 비용은 사용하는 클라이언트의 모델 요금에 따릅니다.

운영 DB에 붙여도 안전한가요?

설정 가능한 접근 제어(읽기 전용 모드, 안전 SQL 파싱)를 제공해 개발·운영 양쪽을 염두에 두고 설계됐습니다. 운영 환경에서는 읽기 전용 모드와 최소 권한 계정을 함께 쓰는 것을 권장하며, 정확한 옵션은 공식 문서 확인을 권합니다.

Supabase나 Neon 같은 매니지드 PostgreSQL에도 쓸 수 있나요?

DATABASE_URI로 접속 가능한 PostgreSQL이면 일반적으로 연결할 수 있습니다. 다만 매니지드 서비스는 일부 확장/권한 제약이 있을 수 있어 인덱스 시뮬레이션 등 기능 호환은 환경에 따라 확인이 필요합니다.