pgmcp

pgmcp는 공식 modelcontextprotocol/go-sdk를 기반으로 구축된 Model Context Protocol용 읽기 전용 PostgreSQL 운영/DBA 서버입니다. DBA가 장애 상황에서 묻는 질문들 — 어떤 문장이 느린지, 이 실행 계획이 왜 느린지, 어떤 인덱스가 죽은 짐인지, 어떤 테이블에서 autovacuum이 뒤처졌는지, 누가 누구를 블로킹하는지, 대기 서버가 얼마나 지연되는지 — 에 답하며, 관례가 아닌 구조적으로 읽기 전용입니다: 쓰기 권한이 없는 전용 데이터베이스 역할, 모든 단일 문장에 문장 타임아웃이 적용된 BEGIN READ ONLY 트랜잭션, 그리고 하나의 SELECT/EXPLAIN/SHOW가 아니거나 읽기 전용 트랜잭션 내에서 상태를 변경할 수 있는 모든 함수를 거부하는 SQL 파서 가드가 있습니다. PostgreSQL 16에서 테스트되었으며, 13 이상이 필요합니다.

설치

Claude Desktop, 원클릭: Releases에서 pgmcp_<version>.mcpb를 다운로드하여 열면 됩니다. Claude Desktop이 Postgres 연결 문자열을 요청하고, OS 키체인에 보관하며, 번들된 바이너리를 직접 실행합니다 — PATH에 아무것도 추가하거나 구성 파일을 편집할 필요가 없습니다. 하나의 번들로 macOS(유니버설)와 Windows(x64)를 모두 지원합니다.

그렇지 않으면 Releases에서 플랫폼에 맞는 바이너리를 다운로드하세요 — darwin, linux, windows, amd64 및 arm64, 체크섬 포함.

또는 Go CLI 도구 go로 소스에서 빌드하세요:

go install github.com/pascalallen/pgmcp/cmd/pgmcp@latest

또는 distroless, 비루트, 멀티 아키텍처인 릴리스 이미지를 실행하세요:

docker run --rm -i -e PGMCP_DATABASE_URL='postgres://…' ghcr.io/pascalallen/pgmcp

pgmcp는 MCP 레지스트리에 io.github.pascalallen/pgmcp로 등록되어 있습니다.

무엇에든 연결하기 전에 읽기 전용 역할을 생성하세요 — 데이터베이스 역할을 참조하세요. 나머지 두 계층에 버그가 있어도 여전히 지켜주는 계층입니다.

Related MCP server: PostgreSQL MCP Server

사용법

하나의 MCP 표면, 두 가지 전송 방식. 어느 것을 실행할지는 구성의 문제이지 다른 빌드가 아닙니다.

Claude Code, stdio — 클라이언트가 바이너리를 실행하고 stdin/stdout으로 통신합니다:

claude mcp add pgmcp --transport stdio \
  --env PGMCP_DATABASE_URL='postgres://pgmcp:…@db.internal:5432/app?sslmode=require' \
  -- pgmcp

Claude Desktop, stdio — Releases에서 .mcpb 번들을 설치하거나(설치 참조), 같은 내용을 claude_desktop_config.json에 직접 작성하세요:

{
  "mcpServers": {
    "pgmcp": {
      "command": "pgmcp",
      "env": {
        "PGMCP_DATABASE_URL": "postgres://pgmcp:…@db.internal:5432/app?sslmode=require"
      }
    }
  }
}

HTTP — 공유 배포를 위한 정적 베어러 키 뒤의 Streamable HTTP. pgmcp는 일반 HTTP만 사용하며 TLS를 직접 종료하지 않습니다. 루프백에서 실행하고 리버스 프록시 뒤에 두세요.

PGMCP_DATABASE_URL='postgres://pgmcp:…@db.internal:5432/app?sslmode=require' \
PGMCP_AUTH_MODE=static \
PGMCP_API_KEYS="$(openssl rand -hex 32)" \
  pgmcp --transport http --listen 127.0.0.1:8080

claude mcp add pgmcp --transport http https://pgmcp.example.com/mcp \
  --header "Authorization: Bearer <key>"

TLS 종료, 스트리밍 전송에 필요한 프록시 설정, ID 공급자에 대한 JWT 인증, 그리고 pgmcp를 claude.ai 사용자 지정 커넥터로 연결하는 방법은 모두 docs/DEPLOYING.md에 있습니다.

도구

모든 도구는 readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false로 주석 처리되어 있으며, 타입이 지정된 출력 스키마를 반환합니다.

query는 자유 형식 SQL을 전달하는 유일한 도구이며 선택 사항입니다. --disable-query는 카탈로그에서 완전히 제거합니다 — 여덟 가지 진단 도구만 필요한 배포는 임시 SQL 표면 없이 실행할 수 있습니다. --query-schemas=public,app는 명명된 스키마로 제한합니다 — 그리고 analyze=true가 문장을 실행하므로 explain도 함께 제한합니다. 이것이 무엇을 막고 무엇을 막지 않는지 docs/SECURITY.md에서 읽어보세요.

리소스 및 프롬프트

구성

모든 설정에는 --flag와 PGMCP_<KEY> 환경 변수가 있습니다. 플래그가 환경보다 우선하고, 환경이 기본값보다 우선합니다. 구성 오류는 모든 위반 키를 하나의 메시지에 나열하고 종료 코드 2로 종료됩니다. 런타임 실패는 1로 종료됩니다.

인증 블록은 HTTP 전송에만 적용됩니다. stdio를 통해서는 운영 체제가 호출자가 누구인지 결정합니다: 바이너리를 실행한 부모 프로세스, 그리고 다른 누구도 아닙니다.

보안 모델

• 세 가지 독립적인 경로로 읽기 전용. 쓰기 권한이 없는 전용 역할(pg_monitor 및 SELECT, 그리고 의도적으로 pg_signal_backend는 아님); 어댑터가 실행하는 모든 문장을 항상 롤백하는 SET LOCAL statement_timeout 및 lock_timeout = '2s'를 사용한 BEGIN READ ONLY; 그리고 파서 수준 가드. 읽기 전용 트랜잭션만으로는 pg_terminate_backend, pg_read_file, pg_sleep 또는 setval을 막을 수 없기 때문입니다.

• SQL 가드는 허용 목록 우선. 최상위 문장 하나, 그리고 그것은 SELECT, EXPLAIN 또는 SHOW여야 합니다. 트리 어디에도 중첩된 쓰기 문장이 없어야 하며, FOR UPDATE/FOR SHARE 잠금 절이 없어야 하고, SELECT INTO가 없어야 하며, 거부된 함수 호출(파일 접근, 백업 및 WAL 제어, 복제 슬롯, 어드바이저리 락, dblink, 시퀀스 변경, 통계 재설정)이 없어야 합니다.

• 스키마 허용 목록은 가드레일이지 경계가 아닙니다. --query-schemas는 구문 분석된 문장에서 테이블 참조를 한정하는 스키마와 대소문자를 구분하지 않고 일치하며, 호출자가 제공한 SQL을 전달하는 두 도구(query 및 explain)를 모두 제한하므로 analyze=true인 explain은 제외한 스키마에 대해 실행될 수 없습니다. 허용된 스키마 내부의 뷰, 집합 반환 함수 또는 SECURITY DEFINER 함수는 여전히 외부를 읽을 수 있습니다. 데이터베이스 권한이 경계이며, 허용 목록은 명백한 경로를 좁힐 뿐입니다.

• 인증되며, 실패 시 폐쇄되고, HTTP를 통해. 정적 키는 조기 종료 없이 저장된 모든 해시에 대해 상수 시간으로 비교됩니다. JWT는 비대칭 알고리즘만 사용하여(alg=none 없음, HMAC 혼동 없음) JWK 세트에 대해 검증되며 필수 iss, aud 및 exp가 있어야 하고, 검증기는 JWKS가 도착할 때까지 키를 보유하지 않으므로 열린 상태가 아닌 닫힌 상태로 시작합니다. RFC 9728 보호 리소스 메타데이터는 토큰을 얻을 수 있는 위치를 알려줍니다. 서버는 인증이 꺼진 상태에서 루프백이 아닌 주소로 시작을 거부합니다.

• 제한적. 주체별 속도 제한, 호출별 타임아웃, 트랜잭션 내부의 문장 타임아웃 및 잠금 타임아웃, query 도구의 행 상한, 결과 구조화 콘텐츠의 상한, 그리고 1MiB 요청 본문 제한.

• 민감한 정보는 기록되지 않습니다. 도구 호출은 이름, 기간, 결과 및 호출자의 사용자 ID를 기록합니다 — 인자, SQL 텍스트, 결과 행 또는 오류 텍스트는 절대 기록하지 않습니다. 구문 분석 실패는 문장을 되풀이하는 대신 고정된 문구로 반환되며, DSN은 연결 오류에서 편집됩니다.

위협 모델, 계층의 전체 목록, 각 계층이 다루지 않는 제한 사항은 docs/SECURITY.md에 있습니다.

테스트

경쟁 탐지기와 커버리지로 테스트 스위트를 실행하세요:

go test -race -cover ./...

통합 테스트는 Postgres 데이터베이스가 필요하며 PGMCP_TEST_DSN이 설정되지 않으면 건너뜁니다. pg_stat_statements가 사전 로드된 임시 Postgres에 대해 실행하려면:

docker run -d --rm --name pg -e POSTGRES_PASSWORD=postgres -p 5544:5432 postgres:16 \
  -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=all
docker exec pg psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS pg_stat_statements"
PGMCP_TEST_DSN="postgres://postgres:postgres@localhost:5544/postgres?sslmode=disable" go test -race -cover ./...

커버리지 프로필을 생성하고 확인하세요:

go test -covermode=count -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

공식 MCP 적합성 스위트로 실행 중인 서버를 테스트하거나 Inspector로 스모크 테스트하세요:

npx -y @modelcontextprotocol/conformance server --url http://127.0.0.1:8080/mcp \
  --expected-failures .github/conformance-expected-failures.yaml
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8080/mcp --transport http --method tools/list

기여

풀 리퀘스트를 환영합니다. 주요 변경 사항의 경우, 변경하고자 하는 내용을 논의하기 위해 먼저 이슈를 열어 주세요.

테스트를 적절히 업데이트해 주세요.

라이선스

MIT