pgops-mcp

AI 에이전트에게 안전하고, 감사 가능하며, 전문가 수준의 제어를 제공하는 프로덕션급 MCP 서버 — 실제 PostgreSQL 데이터베이스와 그 주변의 Docker 스택을 제어합니다. 셸 명령도, Python 스크립트도 없이, 오직 도구만으로.

왜 필요한가

기존 Postgres MCP 서버는 얇은 쿼리 래퍼에 불과합니다: introspection + SELECT. 마이그레이션을 잠금 영향 분석과 함께 처리하는 서버는 없고, EXPLAIN + pg_stat_statements로 성능을 진단하는 서버도 없으며, 데이터베이스가 살고 있는 컨테이너 환경을 이해하는 서버도 없습니다. 오늘날 데이터베이스를 운영하는 에이전트는 맹목적이고 안전하지 않습니다.

pgops-mcp는 운영 두뇌입니다: 스키마 인텔리전스 → 보호된 쿼리 → 마이그레이션 엔진 → 성능 진단 → 환경 인식, 모든 작업을 분류 가능하고, 확인 가능하며, 감사 가능하게 만드는 안전 아키텍처를 갖추고 있습니다.

Related MCP server: PostgreSQL MCP Server

도구 표면 (v0.1)

* 서버가 --approval-mode로 실행되지 않는 한 전혀 등록되지 않으며, 그 경우에도 각 호출은 확인 토큰이 필요합니다. container.exec는 추가로 읽기 전용 진단 명령 허용 목록을 강제합니다 — 셸을 제공하지 않습니다. Docker 소켓은 호스트에서 루트와 동등하므로 기본값은 읽기 전용 액세스입니다.

안전 모델 (핵심 차별점)

• 읽기 전용 / 읽기-쓰기 연결 역할을 분리; 도구는 올바른 역할에 바인딩

• 실행 전 문장 분류 — 무제한 DELETE/UPDATE 차단

• 파괴적 작업은 명시적 확인 토큰 필요

• 실행된 모든 문장은 타이밍과 판정과 함께 추가 전용 감사 로그에 기록

• 타임아웃 계층으로 폭주 쿼리 취소

MCP 표면

원격 액세스 및 에이전트 토큰

stdio는 인증이 필요 없습니다 — 서버는 클라이언트가 생성하는 하위 프로세스이며 열린 포트가 없습니다. HTTP는 인증이 필요하므로 키 없이는 시작을 거부합니다:

pgops-mcp keygen                                    # RS256 keypair
pgops-mcp issue-token --subject my-agent            # read-only by default
pgops-mcp issue-token --subject deploy-bot --scope pgops:read --scope pgops:write
pgops-mcp scopes                                    # which scope each tool needs

pgops-mcp --transport http --public-key ~/.pgops/keys/pgops_public.pem

서버는 공개 키만 보유하므로 토큰을 검증할 수 있지만 발급할 수는 없습니다. 스코프(pgops:read / pgops:write / pgops:admin)는 가드레일과 동일한 위험 등급에 매핑되며, 스코프 항목이 없는 도구는 admin을 요구합니다 — 기본적으로 거부. 달리 지정하지 않는 한 루프백에 바인딩됩니다.

빠른 시작

uv sync
# point at your local Postgres in Docker:
export PGOPS_DSN="postgresql://user:pass@localhost:5432/mydb"
uv run pgops-mcp            # stdio transport for Claude Desktop / Cursor / VS Code

Claude Desktop에 추가:

{
  "mcpServers": {
    "pgops": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pgops-mcp", "pgops-mcp"]
    }
  }
}

문서

• docs/PRD.md — 무엇과 왜, 목표, 비목표

• docs/SPEC.md — 하드 게이트가 있는 단계별 기술 사양

• docs/ARCHITECTURE.md — 시스템 설계 + 트레이드오프

• docs/TOOLS.md — 스키마와 예제가 포함된 전체 도구 카탈로그

• docs/adr/ — 아키텍처 결정 기록

• docs/flow.md — 살아있는 진행 로그

• docs/interview_prep.md — 성장하는 인터뷰 Q&A

상태

0–6b 단계 완료 (319개 테스트, 모든 가드레일, 판정 및 잠금 영향 규칙이 testcontainers를 통해 실제 Postgres로 검증됨 — 목 없음 — 또한 서버를 실제 MCP 하위 프로세스로 stdio 및 인증된 HTTP 서버로 구동하는 엔드투엔드 스위트 포함).

migration.rollback은 의도적으로 아직 열려 있습니다 — docs/TOOLS.md 참조.

120만 행 orders의 타입 변경에 대해 migration.plan이 반환하는 샘플:

ALTER TABLE "orders" ALTER COLUMN "total_cents" TYPE bigint
  op=table_rewrite  risk=high  estimate=4800ms  confidence=medium
  why:   rewrites every row and rebuilds every index, holding AccessExclusiveLock
  SAFER: add a new column of the target type, backfill in batches, sync with a
         trigger, swap the names, then drop the old column

개발 데이터베이스 빠른 시작 (호스트 포트 5433, 로컬 Postgres의 5432와 충돌 방지):

docker compose up -d
export PGOPS_DSN="postgresql://pgops:pgops_dev@localhost:5433/pgops_demo"
uv run pgops-mcp --selfcheck