MCP

PostgreSQL MCP: 먼저 테이블 구조를 본 뒤 읽기 전용 쿼리를 실행

PostgreSQL schema를 확인하거나 읽기 전용 SQL을 실행하려는 사람에게 맞다. 연결 문자열은 직접 준비해야 한다. 읽기 전용 트랜잭션도 데이터베이스를 읽고 비밀번호가 붙을 수 있어 제로 리스크가 아니다.

Official source · modelcontextprotocol/server-postgres

Install

npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb

누구에게 맞나

모델이 PostgreSQL 데이터베이스의 테이블 구조를 보고 읽기 전용 SQL을 실행하게 하려는 사람에게 맞다. 근거는 이렇게 적혀 있다: 이 MCP는 PostgreSQL에 대한 읽기 전용 접근을 제공하며, schema 검사와 읽기 전용 쿼리 실행에 쓴다.

연결 가능한 postgresql:// URL을 제공할 수 있어야 하고, 모델이 테이블 구조와 쿼리 결과를 읽는 것을 받아들여야 한다. 읽기 전용 트랜잭션은 「제로 리스크」가 아니다: 여전히 데이터베이스에 연결하고 데이터를 읽으며, URL에 사용자 이름과 비밀번호가 들어갈 수 있다.

근거는 클라이언트 목록을 적지 않았다. 공식 페이지는 servers-archived 트리에 있고, 근거는 유지보수 상태를 따로 쓰지 않았으므로 현재 주력 구현이라고 단정하지 마라.

3분 만에 첫 시도

NPX 주 경로를 쓰고 Docker를 주 설치로 두지 마라. 클라이언트 MCP 설정에서는 다음을 사용한다:

"command": "npx",
"args": [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://localhost/mydb"
]

마지막 URL을 읽기 전용으로 접근할 권한이 있는 데이터베이스로 바꾼다. 사용자 이름과 비밀번호는 근거대로 postgresql://user:password@host:port/db-name 로 쓸 수 있다. 프로덕션 쓰기 계정이나 전체 비밀번호를 대화에 붙이지 마라.

전제: 이 머신에 npx가 있다. 데이터베이스가 해당 프로세스의 연결을 허용한다. 처음에는 schema만 확인하거나 데이터를 바꾸지 않는 쿼리만 실행한다.

설정 위치: 클라이언트 MCP 서버의 command / args. 세 번째 인자가 연결 문자열이다.

낮은 위험의 첫 호출: 먼저 리소스 postgres://<host>/<table>/schema를 읽어 한 테이블의 열 이름과 타입을 본다. 또는 도구 query를 호출하고 sql 문자열을 넣는다. 근거는 READ ONLY 트랜잭션에서 실행된다고 보장한다. INSERT/UPDATE/DELETE로 「읽기 전용을 검증」하지 마라.

성공 신호: 클라이언트가 연결된 뒤 테이블 schema 리소스를 나열하거나, query가 읽기 전용 결과를 반환한다. 연결에 실패하면 먼저 URL(로컬 DB, 포트, DB 이름)을 고치고 Docker로 바꿔 추측하지 마라. Docker에 대해 근거가 덧붙인 것은: macOS에서 서비스가 호스트에 있으면 host.docker.internal을 쓴다는 점이다.

사용 사례

사례 1: 어떤 테이블에 어떤 열이 있는지 파악한다. postgres://<host>/<table>/schema를 읽는다. 근거는 이것이 데이터베이스 메타데이터에서 자동 발견된 JSON schema이며 열 이름과 데이터 타입을 포함한다고 적는다. 테이블 이름 열거 API는 없다. <host>와 <table>은 실제 연결에 맞게 바꾼다. 보이지 않는 테이블을 지어내지 마라.

사례 2: 이미 존재를 확인한 테이블에 읽기 전용 쿼리를 실행한다. query를 호출하며 파라미터는 sql뿐이다. 근거는 READ ONLY 트랜잭션에서 실행된다고 보장하고, 결과 페이지네이션, 타임아웃, 실행 가능한 SQL 방언 범위는 쓰지 않는다. 따라서 확인할 수 있는 것은 이 SQL이 읽기 전용 쿼리로 이미 연결된 데이터베이스에 들어간다는 점이다. 임시 테이블을 쓰거나 상태를 바꾸는 함수를 호출할 수 있다고 가정하지 마라.

사용 경계

읽기 전용 접근이며 되돌릴 수 있는 쓰기가 아니다. 근거는 undo를 주지 않는다. 연결 문자열에 비밀번호가 들어갈 수 있어 자격 증명과 데이터면 노출이다. 도구는 query뿐이다. Docker와 NPX는 다른 경로이며 주 경로는 NPX를 유지한다. 근거는 연결 풀, SSL, 읽기 전용 역할 강제를 쓰지 않았고, READ ONLY 트랜잭션이 모든 부작용을 막는다고도 하지 않는다(일부 SQL 함수는 여전히 외부 효과가 있을 수 있으나 페이지는 풀어 쓰지 않았다). 페이지는 아카이브 저장소 트리에 있고, 근거는 대체 패키지나 마이그레이션 설명을 제공하지 않는다.