MCPg

PostgreSQL을 위한 프로덕션 등급 Model Context Protocol 서버. AI 에이전트가 Postgres 데이터베이스를 안전하게 검사, 쿼리, 운영, 튜닝할 수 있게 해줍니다 — 카탈로그 인트로스펙션, 쿼리 인텔리전스, 자연어 SQL, 구조적 diff, 하이브리드 검색, 그래프 쿼리, 데이터 이동, 실시간 운영 등을 아우르는 254개의 도구.

라이브로 사용해 보기: MCP 클라이언트 — 또는 MCP Inspector — 를 호스팅된 읽기 전용 데모 엔드포인트 https://devopam-mcpg-demo.hf.space/mcp에 연결하세요. 일회용 데모 데이터에 대해 읽기 도구를 제공합니다. 실제 사용을 위해서는 MCPg를 자신의 데이터베이스 옆에서 실행하세요 (빠른 시작 참조).

📍 등재된 곳

• 공식 MCP 레지스트리

• mcp.so

• mcpservers.org

• Smithery

• Glama

왜 MCPg인가

• 기본적으로 안전합니다. 읽기 전용 액세스 모드. 사용자가 제공한 모든 SQL 문은 실행 전에 검증된 AST 허용 목록을 통과합니다. 식별자 보간은 엄격한 [A-Za-z_][A-Za-z0-9_]* 정규식을 통해 흐릅니다 — 이는 사용자 입력이 문자열 연결을 통해 데이터베이스에 도달하지 않도록 하는 설계 제약입니다. DDL, 셸, LISTEN/NOTIFY 같은 기능은 명시적으로 선택하기 전까지 꺼져 있습니다. 모든 도구는 동일한 게이트에서 파생된 MCP ToolAnnotations (readOnlyHint, openWorldHint)를 게시하므로 클라이언트는 추측 없이 읽기를 자동 승인하고 쓰기를 게이트할 수 있습니다.

• 하나의 서버, 넓은 표면. 애플리케이션 데이터 액세스(쿼리, 검색, 커서, NL→SQL) 및 DBA급 작업(헬스 체크, 인덱스 튜닝, EXPLAIN 분석, 잠금, vacuum, 덤프, 복제본, 마이그레이션)을 단일 MCP 서버에서 제공합니다. 에이전트는 작업을 전환하기 위해 도구를 바꿀 필요가 없습니다.

• PostgreSQL 네이티브 전부. ORM 없음, 추상화 비용 없음 — psycopg3을 직접 사용하고, 모든 pg_* 시스템 뷰를 말하며, TimescaleDB, pgvector, PostGIS, Apache AGE, pg_stat_statements와 통합되고 사용할 수 없을 때는 우아하게 성능이 저하됩니다.

• 데모가 아닌 프로덕션 형태. 연결 풀링, 요청별 SET ROLE 멀티 테넌시, 저하된 호스트 감지가 있는 읽기 복제본 라우팅, 전용 연결이 있는 서버 측 커서, 속도 제한, 정규식 편집이 있는 감사 추적, 시작 시 PG TLS 강제, OIDC JWT 베어러 인증, 세션별 문 / 잠금 시간 초과.

• 관측 가능성 내장. HTTP 전송의 Prometheus /metrics 엔드포인트는 mcpg_tool_calls_total{tool,status} + mcpg_tool_duration_seconds를 노출합니다. 모든 도구 호출은 자격 증명이 편집된 인수와 함께 구조화된 감사 이벤트를 기록합니다.

• 테스트 주도, 다중 버전. 2,500개 이상의 단위 테스트와 CI에서 실제 PostgreSQL 컨테이너에 대해 실행되는 통합 스위트 — 매 푸시마다 PG 14, 15, 16, 17, 18 매트릭스를 다루며, PG 19 (베타) 는 이슈 #120에서 추적되는 실험적(비차단) 항목으로 포함됩니다.

Related MCP server: PostgreSQL MCP Server

설치

PyPI에서 (권장)

pip install mcpg
# or, in an isolated venv exposed globally:
uv tool install mcpg

확인:

mcpg --version

Docker

GitHub Container Registry에서 미리 빌드된 이미지를 가져옵니다 (모든 태그된 릴리스에 게시됨 — :latest는 최신을 추적하거나 :0.6.5 같은 버전을 고정할 수 있습니다):

docker pull ghcr.io/devopam/mcpg:latest
docker run --rm --name mcpg -p 8000:8000 \
    -e MCPG_DATABASE_URL=postgresql://user:pass@host:5432/db \
    -e MCPG_ACCESS_MODE=read-only \
    ghcr.io/devopam/mcpg:latest

Windows PowerShell에서는 끝의 \를 백틱 `으로 바꾸세요 (또는 명령을 한 줄에 넣으세요). 설치 가이드에는 복사 가능한 Linux/macOS, PowerShell, Command Prompt 블록이 있습니다.

또는 소스에서 직접 빌드:

docker build -t mcpg https://github.com/devopam/MCPg.git

다단계 이미지: 런타임 단계는 빌드 툴체인을 제거하고, uid=10001 / gid=10001로 nologin 셸로 실행되며, 애플리케이션 파일은 루트 소유이고 런타임 사용자에게 읽기 전용입니다.

소스에서 (개발자)

git clone https://github.com/devopam/MCPg && cd MCPg
uv sync

uv sync는 모든 런타임 + 개발 종속성이 있는 venv를 만들고 mcpg 콘솔 스크립트를 노출합니다.

자세한 내용은 설치 가이드를 참조하세요.

빠른 시작

원클릭 설치: — Windsurf, JetBrains, Zed, Cline, Antigravity, Qwen Code, Perplexity, ChatGPT, Copilot Studio, Continue, HTTP 클라이언트 설정은 통합 가이드에 있습니다.

Claude Desktop에서 원클릭 설치 (.mcpb)

최신 릴리스에서 mcpg-<version>.mcpb를 다운로드하고 더블 클릭하세요 (또는 Claude Desktop의 설정 → 확장 프로그램으로 드래그하세요). PostgreSQL 연결 URL — OS 키체인에 저장됨 — 과 액세스 모드(기본값은 읽기 전용)를 묻는 메시지가 표시됩니다. 그게 설치의 전부입니다: 번들은 ~2 kB이고 호스트는 플랫폼에 맞는 고정된 mcpg 릴리스를 PyPI에서 해결합니다.

또는 수동으로 연결 (stdio 전송)

이것을 claude_desktop_config.json에 넣으세요 (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "mcpg": {
      "command": "uvx",
      "args": ["mcpg"],
      "env": {
        "MCPG_DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Claude Desktop을 다시 시작하세요. 이제 MCPg 도구 세트를 모델에서 사용할 수 있습니다. Claude에게 다음과 같이 물어볼 수 있습니다:

"이 데이터베이스에 어떤 스키마가 있나요? 각각에 대해 가장 큰 세 개의 테이블을 요약해 주세요."

"이 쿼리가 왜 느린가요? SELECT * FROM orders WHERE customer_id = 42 ORDER BY created_at DESC"

아직 흥미로운 데이터가 없나요? 데모 데이터 세트 시드

MCPG_DATABASE_URL=postgresql://... mcpg --demo

한 명령으로 작고 선별된 전자상거래 데이터 세트(주문 3,000개, 제품 리뷰 900개, 의도적으로 심어진 결함)를 mcpg_demo 스키마에 시드합니다 — 인덱스 어드바이저, 쿼리 계획 분석, 전체 텍스트 검색, PII 감사, 그래프 프로젝션이 모두 첫 시도에서 찾을 실제 무언가를 갖도록 설계되었습니다. 캡처된 연습은 가이드 투어를 참조하고, 언제든지 mcpg --demo-drop로 제거할 수 있습니다.

HTTP 서버로 실행 (IDE 통합, 웹 앱 등)

MCPG_DATABASE_URL=postgresql://user:pass@localhost:5432/mydb \
MCPG_TRANSPORT=streamable-http \
MCPG_HTTP_PORT=8000 \
mcpg

그런 다음 MCP 인식 클라이언트를 http://localhost:8000/mcp (또는 SSE 전송의 경우 /sse)에 연결하세요. 정적 베어러를 위해 MCPG_HTTP_AUTH_TOKEN=...을 설정하거나, OIDC 발급자에 대한 전체 JWT 검증을 위해 MCPG_AUTH_MODE=oidc를 설정하세요.

구성

MCPg는 전적으로 환경 변수를 통해 구성됩니다 — 구성 파일이나 플래그가 없습니다 (CLI의 --version / --demo / --demo-drop은 일회성 명령이지 구성이 아닙니다). 유일하게 필수인 것은 MCPG_DATABASE_URL이며, 나머지는 모두 안전한 기본값이 있습니다.

일반적인 시나리오

전체 참조

핵심

기능 게이트(더 높은 피해 반경 도구에 대한 옵트인)

인증(HTTP 전송 전용)

HTTP 강화(HTTP 전송 전용)

멀티테넌시(SET ROLE)

읽기 복제본

다중 데이터베이스(읽기 전용 보조 데이터베이스)

풀 / 타임아웃 / TLS

하위 프로세스 도구(MCPG_ALLOW_SHELL=true 전용)

LISTEN/NOTIFY (MCPG_ALLOW_LISTEN=true일 때만)

감사(Audit)

비밀(Secrets) 백엔드

기본적으로 모든 비밀은 환경에서 직접 읽습니다. MCPG_SECRETS_BACKEND=file로 설정하면 API 키 / bearer 토큰 / HMAC 키를 마운트된 파일에서 대신 로드합니다 — 파일에 있는 이름이 우선하며, 없는 항목은 환경 변수로 폴백되므로 부분 파일도 동작합니다.

속도 제한(Rate limiting)

캐싱 및 기능 플래그

자연어 SQL

MCPg는 시작 시 환경에서 구성된 모든 공급자를 자동으로 검색합니다 — 보유한 공급업체 키를 원하는 만큼 설정하면 각각 호출 가능해집니다. 19개의 공급자가 기본 내장되어 있습니다. 3개는 퍼스트파티(Anthropic, OpenAI, Gemini)이고, 나머지 16개는 공급업체 사전 설정 엔드포인트로 OpenAI 호환 API를 사용합니다: DeepSeek, Qwen, OpenRouter, Perplexity, xAI(Grok), Groq, Mistral, Together, Fireworks, DeepInfra, Cerebras, Nebius, Hugging Face, GitHub Models, SambaNova, Moonshot(Kimi). 모든 내장 공급자는 플러그 앤 플레이 방식입니다 — 공급업체의 일반적인 API 키 환경 변수를 설정하면 자동 검색되며, 다른 모든 OpenAI 호환 공급업체나 로컬 모델 서버(Ollama, vLLM, LM Studio)도 MCPG_NL2SQL_CUSTOM_PROVIDERS를 통해 구성만으로 연결 가능합니다. 전체 내장 목록은 nl2sql.py의 선언적 레지스트리 하나이므로, 공급업체 추가나 폐기된 기본 모델 갱신은 한 줄의 데이터 변경으로 끝납니다.

MCPG_NL2SQL_PROVIDER가 설정되지 않으면 MCPg는 레지스트리 순서대로 기본값을 자동 선택합니다 — anthropic → openai → gemini가 먼저 유지되어 기존 배포에 영향을 주지 않습니다. translate_nl_to_sql은 선택적 provider="…" 인수를 받아 호출별로 라우팅할 수 있으며, get_server_info는 어떤 공급자가 구성되어 있는지 보고합니다.

사용 예시

MCP 도구는 자연어 지시에 대한 응답으로 에이전트(Claude, Cursor, Continue, …)가 호출합니다. 몇 가지 대표적인 왕복 예시입니다:

스키마 검사

사용자: public 스키마에 어떤 테이블이 있고, 어떤 테이블이 행 수가 가장 많나요?

에이전트 (list_tables + summarize_table × N 사용): 6개 테이블: customers (120만 행), orders (470만 행), line_items (1830만 행), products (340행), addresses (140만 행), audit_log (4580만 행 — 가장 크며, 보존 정책 없이 계속 누적됨).

느린 쿼리 진단

사용자: 다음 쿼리가 8초나 걸리는 이유는 무엇인가요? SELECT * FROM orders o JOIN line_items l ON o.id = l.order_id WHERE o.created_at > now() - interval '7 days'

에이전트 (why_is_this_slow + recommend_indexes 사용): EXPLAIN ANALYZE 결과 orders 테이블에서 created_at 필터로 순차 스캔(sequential scan)이 발생합니다. orders.created_at에 인덱스가 없습니다. 권장 사항: CREATE INDEX CONCURRENTLY orders_created_at_idx ON orders (created_at DESC); 예상 개선 효과: 약 95% 감소 (인덱스 스캔 시 약 3.3만 행만 전체 테이블 대신 접근). 적용 전에 validate_migration을 실행하여 잠금 문제가 없는지 확인하세요.

자연어를 SQL로 변환

사용자: 이번 달에 주문했지만 지난 3개월 동안은 주문한 적이 없는 고객을 찾아 이메일과 총 구매 금액을 보여주세요.

에이전트 (translate_nl_to_sql 사용):

SELECT c.email, SUM(l.price * l.quantity) AS lifetime_spend
FROM customers c
JOIN orders o ON o.customer_id = c.id
JOIN line_items l ON l.order_id = o.id
WHERE EXISTS (
  SELECT 1 FROM orders o2 WHERE o2.customer_id = c.id
    AND o2.created_at >= date_trunc('month', now()))
  AND NOT EXISTS (
  SELECT 1 FROM orders o3 WHERE o3.customer_id = c.id
    AND o3.created_at >= date_trunc('month', now()) - interval '3 months'
    AND o3.created_at <  date_trunc('month', now()))
GROUP BY c.email;

스키마 시각화

사용자: public 스키마의 ER 다이어그램을 그려주세요.

에이전트 (generate_schema_diagram 사용): GitHub / Notion / Obsidian에 바로 붙여넣을 수 있는 Mermaid 다이어그램을 반환합니다.

데이터베이스 감사

사용자: 이 데이터베이스의 현재 상태는 어떤가요?

에이전트 (audit_database 사용): 등급 보고서를 반환합니다: 메모리 및 I/O 점수 92 (GOOD), 트랜잭션 및 연결 78 (WARNING: 롤백률 0.4%, 앱 로그 확인), 동시성 및 잠금 60 (CRITICAL: 대기 중인 백엔드 14개), 정리 및 블로트 88 (GOOD), 느린 쿼리 70 (WARNING: 상위 쿼리 템플릿 5000회 실행, 평균 90ms — optimize_query 참조).

쓰기 작업 실행

사용자: 5년 이상 된 모든 주문을 소프트 삭제하세요.

에이전트 (run_write + MCPG_AUDIT_PERSIST=true 사용): 안전 SQL 커널을 통해 명령문을 검증하고, 트랜잭션 내에서 실행하며, 영향을 받은 행 수를 반환하고, 호출 기록(sql + 인자 — 정규식으로 민감정보 마스킹 — + 상태)을 mcpg_audit.events에 저장하여 사후 검토가 가능하게 합니다.

더 많은 실용 레시피 — 멀티테넌트 라우팅, RLS 테스트, 자연어→SQL, 하이브리드 벡터 + FTS 검색, Apache AGE Cypher, TimescaleDB, ORM 스키마 내보내기, 서버 사이드 커서 — 는 docs/cookbook.md를 참조하세요.

구성 요소

간략한 구성 요소 목록. 전체 최신 도구 참조는 docs/tools.md를, 단계별 안내는 docs/tour.md를 참조하세요.

• 카탈로그 검사 — 스키마, 테이블, 컬럼, 인덱스, 제약 조건, 뷰, 함수, 트리거, 시퀀스, 파티션, 정책, 역할, 권한, enum, 도메인, 복합 타입, FDW, publication, subscription, 확장, 생성 컬럼.

• 쿼리 인텔리전스 — run_select, run_select_parallel, explain_query, analyze_query_plan, why_is_this_slow, recommend_indexes, analyze_workload, check_database_health, detect_n_plus_one, audit_database.

• 검색 — fuzzy_search (트라이그램), full_text_search, vector_search, hybrid_search (pgvector + FTS via RRF), geo_search (PostGIS k-NN).

• 자연어 → SQL — translate_nl_to_sql (내장 공급자 22개 — Anthropic, OpenAI, Gemini, xAI, Groq, Mistral, Hugging Face, … — 및 모든 사용자 지정 OpenAI 호환 엔드포인트; 출력은 수기 작성 쿼리와 동일한 안전 SQL 커널을 통과합니다).

• 시각화 — generate_schema_diagram (ER), generate_fk_cascade_graph (ON DELETE CASCADE의 영향 범위), generate_graph_diagram (Apache AGE 속성 그래프).

• 구조 비교 및 마이그레이션 — compare_schemas, validate_migration, 단계별 prepare_migration / complete_migration / cancel_migration 워크플로우.

• Apache AGE 그래프 + Cypher — list_graphs, describe_graph, run_cypher, create_graph, drop_graph, generate_graph_diagram.

• 복합 및 어드바이저 도구 — summarize_table, find_unused_objects, find_sensitive_columns (PII 휴리스틱), lint_naming_conventions, test_rls_for_role, list_locks, find_blocking_chains, read_pg_stat_io (PG16+), generate_test_data.

• 실시간 운영 및 유지보수 — list_active_queries, verify_connection_encryption (실시간 연결의 TLS 상태), run_maintenance (VACUUM/ANALYZE), prune_audit_events (감사 보존), cancel_query, terminate_backend, run_write, run_ddl, enable_extension.

• 데이터 이동 — export_query / export_table (CSV/JSON), dump_database / restore_database, import_csv / import_json (COPY FROM STDIN), copy_table_between_databases.

• 서버 사이드 커서 — open_cursor, fetch_cursor, close_cursor, list_cursors — 수백만 행의 페이지네이션 읽기용.

• TimescaleDB — list_hypertables, list_chunks, create_hypertable, add_compression_policy, add_retention_policy.

• ORM 스키마 내보내기 — Prisma, Drizzle, SQLAlchemy, sqlc, Diesel, jOOQ, Ent, Ecto.

• 이벤트 스트림 — subscribe_channel, poll_notifications, unsubscribe_channel, list_notification_subscriptions — PostgreSQL LISTEN/NOTIFY를 MCP 폴 모델로 연결.

• 관측성 — Prometheus /metrics 엔드포인트 + stdio용 get_metrics_exposition 도구; 정규식 기반 자격 증명 마스킹이 적용된 구조화된 감사 추적.

문서

• docs/installation.md — 설치 및 구성

• docs/tour.md — 도구 둘러보기 가이드

• docs/cookbook.md — 실용적인 에이전트 레시피

• docs/tools.md — 전체 도구 참조

• docs/architecture.md — 구성 요소 간의 관계

• docs/scaling.md — 풀 크기 조정, 복제본, 성능

• docs/security-hardening.md — 보안 기능 로드맵

• docs/release-process.md — PyPI 릴리스 프로세스

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

• https://devopam.github.io/MCPg/ 에서 탐색

보안

• 취약점 보고: SECURITY.md 참조. 90일 조정 공개 창구; 보고는 devopam@gmail.com으로.

• 심층 방어: 기능 게이트, SafeSQL 커널, 식별자 허용 목록, 감사 로그, 시작 시 PG TLS, 속도 제한, OIDC JWT 검증, 세션별 타임아웃.

• 제공된(✅) 및 대기 중(⬜) 강화 항목의 진행 로드맵은 docs/security-hardening.md 참조.

개인정보 보호정책

MCPg는 자체 호스팅 방식입니다. 데이터베이스 내용이 인프라를 벗어나지 않으며, 어떠한 원격 측정이나 전화 집(phone-home) 기능도 없습니다. 문서화된 유일한 예외는 옵트인(opt-in) 방식의 translate_nl_to_sql 도구로, 이 도구는 사용자의 질문과 스키마 컨텍스트(이름만, 행 데이터는 아님)를 사용자가 직접 구성한 LLM 공급자에게 전송합니다. 전체 정책 — 데이터 수집, 사용, 저장, 제3자 공유, 보존, 연락처 — 은 PRIVACY.md에 있습니다.

릴리스 노트 및 변경 로그

전체 버전 기록은 CHANGELOG.md, 릴리스 절차는 docs/release-process.md, 다운로드 가능한 산출물은 GitHub Releases 페이지를 참조하세요.

기여

풀 리퀘스트 환영합니다 — 개발 루프 설정은 CONTRIBUTING.md, 테스트 규칙과 PR별 리뷰 체크리스트도 해당 문서를 참조하세요.

라이선스

MIT — LICENSE 참조. SQL 안전 커널(src/mcpg/sql/)은 MIT 라이선스의 crystaldba/postgres-mcp를 기반으로 재작성된 1차(자체) 코드입니다. 계보에 대해서는 NOTICE를 참조하세요.

래핑된 확장 기능 — 알아두어야 할 라이선스

MCPg의 소스 코드는 MIT이지만, 래핑하는 각 PostgreSQL 확장 기능은 각자의 라이선스를 따릅니다. 래퍼는 완전히 분리된 형태입니다(SQL 수준 호출만 하며, MCPg의 Python 프로세스에 정적 또는 동적 링크를 하지 않으므로), MCPg 프로젝트 자체는 이들 중 어떤 것의 파생 저작물도 아닙니다. MCPg + 특정 확장 기능을 기반으로 서비스를 운영하는 운영자는 해당 확장 기능의 라이선스가 부과하는 의무를 그대로 부담합니다 — 확장 기능을 직접 설치하는 것과 동일합니다. 아래 표는 래핑된 확장 기능별 라이선스를 명시하여 정보에 입각한 선택을 돕습니다.

이 표는 출발점일 뿐입니다 — 특정 배포 환경에 대한 구속력 있는 판단은 확장 기능의 원본 LICENSE 파일과 (법적으로 문제가 될 경우) 자체 법률 자문을 참조하세요.

면책 조항. MCPg를 프로덕션 수준으로 끌어올리기 위해 최선의 노력을 기울였지만, 이 프로젝트는 여전히 활발히 개발 중이며 문제가 있을 수 있습니다. 면책 세부 사항은 라이선스 조항을 참조하세요.