Postgres MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

읽기 전용 설계 — INSERT/UPDATE/DELETE/DDL은 프로토콜 수준에서 차단됩니다.
전체 스키마 검사: 테이블, 열, 유형, 인덱스, 외래 키
성능 분석을 위한 쿼리 계획(EXPLAIN)을 반환합니다.
표준 postgres:// 연결 문자열 — 모든 PG 호환 DB(Postgres, Neon, Supabase, RDS, Aiven 등)에서 작동합니다.

라이브 데모

실제 사용 모습

postgres.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "postgres",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://..."
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "postgres": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres",
          "postgresql://..."
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://...

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Postgres

SQL을 건드리지 않고 임시 비즈니스 질문에 답변

👤 PM, 창립자, SQL을 작성하고 싶지 않은 사람 ⏱ ~10 min beginner

언제 쓸까: 데이터('이번 주에 몇 명의 사용자가 돌아왔습니까?')에 대한 질문이 있는데 BI 대시보드에는 해당 질문이 없습니다.

사전 조건

복제본에 대한 읽기 전용 postgres:// 연결 문자열 — 가장 많이 관리되는 PG(RDS, Neon, Supabase)를 사용하면 읽기 전용 자격 증명을 만들 수 있습니다.
Claude가 실행되는 곳에서 DB로의 네트워크 액세스 — VPN 또는 IP 허용 목록에 컴퓨터를 추가하세요.

흐름

Claude에게 관련 테이블을 먼저 검토하게 하세요.

DB의 모든 테이블을 나열합니다. 사용자, 주문, 세션과 관련된 테이블의 경우 해당 스키마를 설명하세요.✓ 복사됨

→ 쿼리 전 스키마 개요
실제 질문을 해보세요

지난 30일 동안 가입했지만 아직 주문하지 않은 사용자는 몇 명입니까? 가입 주별로 그룹화합니다.✓ 복사됨

→ Claude는 SQL을 작성하고 실행하고 결과 테이블을 반환합니다.
주의 사항에 대한 프로브

이 숫자가 오해의 소지가 있을 수 있는 이유가 있나요? 소프트 삭제? Created_at의 시간대? 제외해야 하는 특정 사용자 유형은 무엇입니까?✓ 복사됨

→ 데이터 문제에 대한 정직한 설명

결과: SQL, 결과 및 주의 사항이 포함된 비즈니스 질문에 대한 방어 가능한 답변을 데이터 팀을 위해 2일을 기다리는 대신 2분 만에 제공합니다.

함정

Claude는 제한 없이 가장 큰 테이블을 검색하는 쿼리를 작성합니다. — 연결에서 statement_timeout = '30s'를 설정하고 시스템 프롬프트에 '기본적으로 항상 LIMIT 1000 포함'을 추가하세요.
'사용자' 계산은 사용자로 계산되는 항목에 따라 다릅니다(삭제? 봇? 테스트?) — Claude에게 사전에 '삭제_at가 NULL이 아닌 행 제외' 등의 규칙을 알려주세요.

함께 쓰기: notion

쿼리 속도가 느린 이유 진단 및 인덱스 제안

👤 백엔드 엔지니어, DBA ⏱ ~15 min intermediate

언제 쓸까: 예상보다 느린 쿼리가 있습니다. EXPLAIN ANALYZE 출력을 읽는 데 지치지 않는 두 번째 눈이 필요합니다.

흐름

쿼리 계획 가져오기

이 쿼리에 대해 EXPLAIN ANALYZE를 실행하세요: [paste]. 기획자가 하는 일을 안내해 주세요.✓ 복사됨

→ 단계별 계획 연습
비용 요인 파악

비용의 대부분을 담당하는 단계는 무엇입니까? 순차 스캔인가요, 잘못된 조인 순서인가요, 아니면 비용이 많이 드는 필터링인가요?✓ 복사됨

→ 이유가 있는 특정 노드 식별
색인 제안 또는 재작성

이를 빠르게 수행하려면 가장 작은 변화를 제안하세요. 쿼리를 다시 작성하는 것보다 인덱스를 추가하는 것을 선호하지만 인덱스가 >1 쿼리에 유용한 경우에만 해당됩니다.✓ 복사됨

→ 구체적인 CREATE INDEX 문 또는 다시 작성된 쿼리

결과: EXPLAIN을 다시 실행하여 확인할 수 있는 추론이 포함된 인덱싱되거나 다시 작성된 쿼리입니다.

함정

대표성이 없는 데이터 세트(소형 개발 DB)에 대한 EXPLAIN은 잘못된 계획을 제공합니다. — 항상 프로덕션 형태의 데이터가 있는 데이터베이스에 대해 EXPLAIN을 실행하십시오. 그렇지 않으면 그 계획은 허구이다
인덱스 추가는 무료인 것처럼 보이지만 쓰기 속도가 느려집니다. — Claude에게 추가를 요청하기 전에 EXPLAIN을 사용하여 인덱스가 사용될지 확인하도록 지시합니다.

함께 쓰기: sentry

데이터 품질 문제에 대한 테이블 감사

👤 데이터 엔지니어, 익숙하지 않은 스키마를 상속받는 사람 ⏱ ~25 min intermediate

언제 쓸까: 당신은 자신이 디자인하지 않은 테이블 위에 기능을 구축하려고 하는데 테이블에 문제가 있다고 의심됩니다.

흐름

NULL/중복/고아 검사 배터리 실행

orders 테이블의 경우: 열당 NULL 값 계산, 일부 자연 키(예: (user_id, Stripe_지불_intent_id))로 중복 행 계산, 삭제된 상위 행을 가리키는 외래 키가 있는 행 계산.✓ 복사됨

→ 수표당 문제 수
가치 분포의 이상한 점을 확인하세요.

total_cents의 최소, 최대 및 백분위수 분포는 무엇입니까? 0 또는 음수 값을 갖는 행이 의심스러울 정도로 많습니까?✓ 복사됨

→ 분포 통계, 이상값 플래그 지정
예상되는 비즈니스 규칙과 대조 확인

모든 '완료된' 주문에는 null이 아닌 'paid_at'이 있어야 합니다. 예외가 있나요?✓ 복사됨

→ 위반 횟수 + 샘플 ID

결과: 각각 개수와 수정 경로가 포함된 구체적인 데이터 무결성 버그의 짧은 목록입니다.

함정

일부 '문제'는 의도적인 역사적 유물(데이터 마이그레이션)입니다. — 버그라고 가정하기 전에 항상 이력을 아는 사람에게 확인하세요.

팀을 위한 스키마 문서 자동 생성

👤 새로운 엔지니어를 온보딩하는 기술 리더 ⏱ ~20 min beginner

언제 쓸까: 귀하의 DB에는 40개의 테이블이 있고 위키에는 0개의 테이블이 있습니다. 신입 사원이 계속 '이 열이 무엇인가요?'라고 묻습니다.

흐름

모든 테이블과 해당 스키마 가져오기

공개 스키마의 모든 테이블을 나열합니다. 각각에 대해 열, 유형, null 허용 여부, 기본값 및 외래 키를 제공합니다.✓ 복사됨

→ 전체 스키마 덤프
네이밍 + 샘플 데이터로 목적 유추

각 테이블에 대해 3개의 행을 샘플링하고 이 테이블이 우리 비즈니스에서 나타내는 내용을 한 문단으로 설명합니다.✓ 복사됨

→ 테이블별 산문 설명
알 수 없거나 의심스러운 테이블에 플래그 지정

사용되지 않은 것처럼 보이거나 목적을 유추할 수 없는 테이블이 있습니까? 원저자에게 물어볼 수 있도록 목록을 작성하세요.✓ 복사됨

→ 솔직한 '이게 뭔지 모르겠어요' 목록

결과: 팀이 Notion이나 Wiki에 드롭할 수 있는 Markdown 문서는 신입 사원이 알아야 할 내용의 80%를 다루고 있습니다.

함정

LLM 컨텍스트로 민감한 데이터(PII) 샘플링 — PII가 있는 테이블의 경우 Claude에게 샘플링 행 없이 스키마만 설명하도록 요청하세요.

함께 쓰기: notion · filesystem

원시 이벤트 데이터에서 A/B 테스트 결과 계산

👤 제품 분석가, 성장 엔지니어 ⏱ ~30 min advanced

언제 쓸까: 실험을 실행했고 데이터가 DB에 있으며 SQL을 직접 작성하지 않고 유의미한 숫자를 원합니다.

사전 조건

실험 할당 + 전환 이벤트가 포함된 이벤트 표 — 표준 스키마: 이벤트(user_id, 실험, 변형, 타임스탬프), 전환(user_id, 유형, 타임스탬프)

흐름

변형당 전환율 계산

실험 'checkout-redesign-2026'의 경우: 각 변형에 할당된 사용자 수는 얼마이며, 변형당 전환율([전환 이벤트]별)은 얼마입니까?✓ 복사됨

→ 요율이 포함된 변형별 테이블
통계적 유의성 계산

대조와 처리 간의 차이에 대한 카이제곱 p-값을 계산합니다. 결과가 p < 0.05에서 통계적으로 유의합니까?✓ 복사됨

→ 평결이 있는 p-값
숫자를 확인해 보세요

표본 크기가 균형을 이루고 있나요? 실험이 충분히 오래 진행되었나요? 결과가 반전되는 세그먼트가 있나요?✓ 복사됨

→ p-값뿐만 아니라 상태 점검

결과: SQL, 숫자, 주의 사항을 포함하여 통계적으로 방어 가능한 A/B 테스트 판독값입니다.

함정

사전 정의된 표본 크기가 발생하기 전에 결과를 엿보면 거짓 긍정이 발생합니다. — Claude가 유의성을 계산하기 전에 테스트가 목표 표본 크기에 도달했는지 확인하도록 합니다.

함께 쓰기: notion

조합

다른 MCP와 조합해 10배 효율

postgres + notion

DB에 접근할 수 없는 이해관계자를 위해 쿼리를 실행하고 결과를 Notion 테이블로 게시합니다.

이번 분기 평생 수익 기준으로 상위 10명의 고객을 쿼리한 다음 결과를 형식화된 테이블로 '판매 보고서'에 Notion 페이지를 만듭니다.✓ 복사됨

postgres + sentry

오류가 있는 상호 참조 DB 상태 — 오류에 레코드 ID가 언급되면 찾아보세요.

Sentry 문제 WEB-3a91에서는 order_id 99214를 언급합니다. 해당 주문을 찾아 행 데이터에 충돌을 설명할 수 있는 항목이 있는지 알려주세요.✓ 복사됨

postgres + filesystem

다운스트림 사용을 위해 쿼리 결과를 CSV/JSON으로 내보내기

내 이탈 집단 쿼리를 실행하고 결과를 /reports/churn-2026-04.csv로 저장합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
list_tables	schema?: str	모든 세션의 첫 번째 단계 - 스키마 발견	free
describe_table	table: str, schema?: str	쿼리하기 전에 특정 테이블의 전체 구조 가져오기	free
query	sql: str	읽기 전용 SQL 실행 — SELECT 전용	depends on query

비용 및 제한

운영 비용

API 쿼터: DB의 연결 제한 및 쿼리 시간 초과에 따라 제한됨
호출당 토큰: 스키마 쿼리: ~500개 토큰. 결과 세트: 행 수에 따라 다름 — LIMIT로 제한
금액: 무료 — 비용은 DB 호스팅 청구서에 관계없이 적용됩니다.
팁: 연결에 항상 statement_timeout(예: ?options=-c%20statement_timeout%3D30000)을 설정하여 폭주 쿼리가 DB를 중단할 수 없도록 하세요.

보안

권한, 시크릿, 파급범위

최소 스코프: SELECT on the tables you want exposed

자격 증명 저장: env var의 연결 문자열입니다. 전용 읽기 전용 역할을 사용하십시오:

CREATE ROLE claude_readonly LOGIN PASSWORD '...'; claude_readonly에 공개 스키마의 모든 테이블에 대한 선택 권한 부여;

데이터 외부 송신: 귀하의 DB에 대한 모든 쿼리; 귀하가 사용하는 LLM 제공업체에 결과 행이 전달됩니다.

절대 부여 금지: INSERT UPDATE DELETE DROP TRUNCATE ALTER

읽기 전용 쿼리라도 비용이 많이 들 수 있습니다. prod에 연결하는 경우 'SET 문_시간 초과'로 래핑하세요.
프로덕션에서 읽기 복제본 연결 문자열을 사용합니다.

문제 해결

자주 발생하는 오류와 해결

FATAL: password authentication failed

연결 문자열을 확인하세요. 일반적인 원인: URL로 인코딩되지 않은 비밀번호에 특수 문자가 포함되어 있습니다.

확인: psql 'postgres://...' -c 'SELECT 1'

no pg_hba.conf entry / SSL required

연결 문자열에 ?sslmode=require를 추가합니다. 대부분의 관리형 Postgre에는 SSL이 필요합니다.

permission denied for table X

역할에는 해당 테이블에 대한 SELECT가 없습니다. GRANT SELECT ON X TO clude_readonly를 실행합니다.

확인: psql -c '\dp X'

canceling statement due to statement timeout

쿼리가 너무 느렸습니다. 이를 최적화하거나(인덱스 추가, WHERE 절 범위 좁히기) 해당 연결에 대한 시간 초과를 늘리십시오.

대안

Postgres 다른 것과 비교

대안	언제 쓰나	단점/장점
Supabase MCP	귀하는 Supabase를 사용하고 있습니다. 전체 프로젝트 관리와 SQL을 얻으세요	쓰기 액세스가 포함됩니다. 생산에 덜 안전함
Neon MCP	귀하는 Neon을 사용하고 있습니다. 안전한 마이그레이션 테스트를 위해 분기를 추가합니다.	Neon 관련 기능은 Neon DB에서만 작동합니다.
dbHub	하나의 MCP에 다중 데이터베이스 지원(Postgres, MySQL, MongoDB 등)이 필요합니다.	최신; 더 많은 DB를 지원하지만 각 통합이 더 얕습니다.
sqlite MCP	서버가 아닌 로컬 파일 기반 DB	동시 액세스 없음, 네트워크 없음, 설정 없음

Postgres

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: Postgres

SQL을 건드리지 않고 임시 비즈니스 질문에 답변

사전 조건

흐름

함정

쿼리 속도가 느린 이유 진단 및 인덱스 제안

흐름

함정

데이터 품질 문제에 대한 테이블 감사

흐름

함정

팀을 위한 스키마 문서 자동 생성

흐름

함정

원시 이벤트 데이터에서 A/B 테스트 결과 계산

사전 조건

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

Postgres 다른 것과 비교

더 보기

리소스