PostgreSQL MCP란?

PostgreSQL MCP는 AI 모델이 PostgreSQL 데이터베이스에 직접 접근하여 스키마를 탐색하고, 쿼리를 실행할 수 있게 해주는 MCP 서버입니다. Supabase, Neon, Railway, AWS RDS 등 PostgreSQL 호환 서비스와 모두 연동되며, 공식 패키지 @modelcontextprotocol/server-postgres는 Anthropic이 직접 유지보수합니다. 프로젝트 초기 단계에서 DB 탐색·디버깅에 들이는 시간의 상당 부분이 반복 작업(테이블 구조 훑기, 간단한 집계, 인덱스 확인 등)이라는 점을 고려하면, 이 서버 하나로 얻는 생산성 향상이 상당히 큽니다.

이전 편에서 GitHub MCP를 다뤘다면, 이제 데이터베이스 영역으로 확장합니다. 코드 저장소와 데이터베이스를 동시에 AI에게 노출하면, "이 PR이 바꾼 스키마가 기존 데이터와 호환되는가" 같은 코드-데이터 교차 질문까지 자연어로 던질 수 있게 됩니다. 이번 편은 그 조합의 기반이 되는 DB 쪽 설정과 실전 활용 패턴에 집중합니다.

!mcp-guide-05-postgresql 본문 이미지 1

설정

설정의 핵심은 연결 문자열(Connection String) 하나입니다. 로컬 개발용 로컬호스트 인스턴스부터 Supabase의 매니지드 인스턴스까지 동일한 방식으로 연결하며, 프로덕션에서는 반드시 별도의 읽기 전용 사용자를 만들고 그 자격 증명을 환경 변수로 주입합니다. 아래 두 가지 예시는 개발 환경 직접 연결과 Supabase Connection Pooler 연결을 각각 보여 줍니다.

기본 PostgreSQL 연결

{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://username:password@localhost:5432/mydb"
]
}
}
}

Supabase 연결

Supabase의 Connection Pooler를 사용하면 서버리스 환경에서도 안정적으로 연결됩니다.

{
"mcpServers": {
"supabase-db": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://postgres.xxxx:password@aws-0-ap-northeast-2.pooler.supabase.com:6543/postgres"
]
}
}
}

Connection String은 Supabase Dashboard > Settings > Database에서 확인할 수 있습니다.

!데이터베이스 스키마 탐색

핵심 활용

PostgreSQL MCP가 제공하는 실전 가치는 크게 세 가지 범주로 나뉩니다. 첫째는 스키마 탐색으로, 낯선 프로젝트에 투입됐을 때 테이블 구조와 관계를 단번에 파악할 수 있습니다. 둘째는 쿼리 실행으로, 집계·조인·통계 쿼리를 자연어 한 줄로 얻어낼 수 있어 임시 대시보드 수준의 인사이트를 빠르게 생성합니다. 셋째는 데이터 정합성 감사로, 외래 키 누락·고아 레코드·중복 같은 현장 고질병을 한 번에 스캔합니다. 아래 예시는 Claude Code에서 실제로 사용하는 자연어 명령 패턴입니다.

스키마 탐색

# 전체 테이블 목록 확인
claude "데이터베이스의 모든 테이블과 각 테이블의 컬럼 정보를 보여줘"

특정 테이블 구조 분석
claude "users 테이블의 스키마를 분석하고, 인덱스와 제약 조건도 보여줘"

테이블 간 관계 파악
claude "외래 키 관계를 기반으로 ERD를 설명해줘"

쿼리 실행

# 데이터 조회
claude "지난 7일간 가입한 사용자 수를 날짜별로 집계해줘"

성능 분석
claude "가장 느린 쿼리 top 5를 pg_stat_statements에서 찾아줘"

데이터 정합성 확인
claude "orders 테이블에서 user_id가 users 테이블에 없는 고아 레코드를 찾아줘"

Supabase RLS 정책 확인

# RLS 정책 목록 조회
claude "모든 테이블의 RLS 정책을 조회하고, 정책이 없는 테이블을 찾아줘"

실제 쿼리 예시입니다.

-- PostgreSQL MCP가 내부적으로 실행하는 쿼리 예시
SELECT schemaname, tablename, policyname, permissive, roles, cmd, qual
FROM pg_policies
WHERE schemaname = 'public'
ORDER BY tablename, policyname;

-- RLS가 활성화되었지만 정책이 없는 테이블 탐지
SELECT t.tablename
FROM pg_tables t
LEFT JOIN pg_policies p ON t.tablename = p.tablename
WHERE t.schemaname = 'public'
AND t.rowsecurity = true
AND p.policyname IS NULL;

!쿼리 실행 결과

!mcp-guide-05-postgresql 본문 이미지 2

실전 워크플로우: 마이그레이션 생성

PostgreSQL MCP의 강력한 활용 사례는 AI가 스키마를 분석하고 마이그레이션을 자동 생성하는 것입니다. 손으로 작성하던 ALTER TABLE 스크립트와 롤백 스크립트를 AI가 쌍으로 만들어 주기 때문에, "변경 사항은 알지만 SQL 문법이 헷갈린다"는 단계에서 발생하는 실수를 크게 줄일 수 있습니다. 단, 생성된 마이그레이션은 반드시 스테이징에서 먼저 적용해 보고, 프로덕션에는 리뷰를 거쳐 사람이 최종 승인하는 절차를 유지해야 합니다.

# 1. 현재 스키마 분석
claude "현재 데이터베이스 스키마를 분석해줘"

2. 변경 사항 기반 마이그레이션 생성
claude "users 테이블에 avatar_url 컬럼을 추가하는 마이그레이션 SQL을 작성해줘.
롤백 SQL도 함께 포함해."

AI가 생성하는 마이그레이션 예시입니다.

-- Migration: add_avatar_url_to_users
-- Created: 2026-05-09

BEGIN;

ALTER TABLE public.users
ADD COLUMN avatar_url TEXT;

COMMENT ON COLUMN public.users.avatar_url IS '사용자 프로필 이미지 URL';

COMMIT;

-- Rollback
-- BEGIN;
-- ALTER TABLE public.users DROP COLUMN avatar_url;
-- COMMIT;

보안 가이드

데이터베이스 접근은 가장 민감한 영역입니다. 반드시 다음 원칙을 따르세요. 특히 운영 DB에 바로 연결하는 구성은 절대 권장하지 않으며, 개발·스테이징 환경에서 충분히 검증한 뒤 운영에서는 읽기 전용 복제본(리드 레플리카)이나 익명화된 샘플 DB를 별도로 노출하는 패턴을 추천합니다.

읽기 전용 사용자 생성

-- 프로덕션 환경에서는 반드시 읽기 전용 사용자를 사용
CREATE ROLE mcp_readonly WITH LOGIN PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE mydb TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;

보안 체크리스트

• 프로덕션 DB에는 읽기 전용 계정만 사용합니다
• Connection String에 비밀번호를 직접 넣지 말고 환경 변수를 사용합니다
• 개발/스테이징 환경에서 먼저 테스트합니다
• 민감한 테이블(결제 정보, 개인정보)에는 접근 권한을 부여하지 않습니다

다음 단계

데이터베이스 자동화를 익혔다면, 다음 편에서는 Slack MCP를 활용한 팀 커뮤니케이션 자동화를 다룹니다.

---

MCP 실전 가이드 시리즈

MCP란 무엇인가

첫 MCP 서버 만들기

Filesystem MCP 실전

GitHub MCP 자동화

PostgreSQL MCP 쿼리 (현재 글)

Slack MCP 커뮤니케이션

Linear MCP 프로젝트 관리

커스텀 MCP 서버

MCP 보안 가이드

MCP 생태계 총정리

PostgreSQL 성능 튜닝 가이드도 함께 참고하세요. AI K LINK Kit에서 더 많은 데이터베이스 MCP 서버를 탐색할 수 있습니다.