PG-MCP: PostgreSQL 데이터베이스를 위한 MCP 서버

안녕하세요.

오늘은 PostgreSQL 데이터베이스를 인공지능(AI) 에이전트가 더 쉽게 탐색하고 활용할 수 있도록 도와주는 PG-MCP 프로젝트에 대해 소개드립니다. 이 글에서는 PG-MCP의 주요 기능, 설치 방법, 사용법, 그리고 AI와의 연동까지 자세히 설명해드릴게요.

---

PG-MCP란 무엇인가?

PG-MCP(PostgreSQL Model Context Protocol)는 PostgreSQL 데이터베이스를 AI 에이전트가 이해하고 사용할 수 있도록 도와주는 MCP 서버 구현체입니다. 간단히 말해, AI가 데이터베이스 구조와 내용을 효과적으로 탐색하고 분석할 수 있도록 API와 도구를 제공하는 서버입니다.

 

MCP에 대한 자세한 내용은 아래를 참고하세요.

2025.03.12 - [AI 트렌드] - [AI 트렌드] MCP vs API 비교: AI 통합 방식의 혁신적 변화

[AI 트렌드] MCP vs API 비교: AI 통합 방식의 혁신적 변화

 

---

PG-MCP의 주요 기능

✅ 완전한 서버 구조

PG-MCP는 단순한 스크립트가 아닌, 프로덕션 환경에서 사용할 수 있도록 구축된 완전한 서버입니다. SSE(Server-Sent Events) 방식을 통해 실시간 통신도 지원합니다.

🔄 다중 데이터베이스 연결 지원

여러 개의 PostgreSQL 데이터베이스에 동시에 연결할 수 있어, 분산된 데이터 환경에서도 유연하게 활용할 수 있습니다.

📚 풍부한 카탈로그 정보 제공

데이터베이스의 테이블, 컬럼, 제약 조건 등을 자동으로 추출해 설명과 함께 제공합니다. 덕분에 스키마 구조를 이해하는 데 큰 도움이 됩니다.

---

확장 정보 관리 (Extension Context)

🗺️ PostGIS 지원

공간 데이터를 처리하는 PostgreSQL 확장인 PostGIS의 함수와 데이터 타입 정보를 YAML 형식으로 내장하고 있습니다.

🔎 pgvector 지원

벡터 기반 유사도 검색을 위한 pgvector 기능도 지원하며, 벡터 쿼리를 위한 예시와 설명도 포함되어 있습니다.

⚙️ YAML 기반 확장 설정

추가적인 확장 기능도 YAML 설정 파일을 통해 손쉽게 추가하거나 편집할 수 있습니다.

---

반응형

쿼리 도구 및 설명 기능

📥 pg_query: 읽기 전용 쿼리 실행

등록한 데이터베이스 연결 ID를 이용해 SELECT와 같은 읽기 전용 쿼리를 실행할 수 있습니다.

🧠 pg_explain: 쿼리 실행 계획 해석

쿼리의 실행 계획을 JSON 형식으로 분석해, 쿼리의 효율성을 평가하거나 개선 방향을 파악하는 데 도움이 됩니다.

---

스키마 탐색 및 데이터 접근

🧱 스키마 및 테이블 구조 탐색

각 데이터베이스의 스키마와 테이블을 설명과 함께 탐색할 수 있으며, 컬럼의 데이터 타입과 제약 조건도 확인 가능합니다.

📊 샘플 데이터 조회

테이블의 일부 데이터를 페이징 방식으로 조회할 수 있어 데이터 구조를 이해하기 좋습니다.

🧮 행 수 추정

테이블에 저장된 데이터의 대략적인 행 수도 제공되어 쿼리 최적화나 인덱스 설계에 유용합니다.

---

AI 에이전트와의 연동

🧪 기본 서버 테스트

python test.py "postgresql://username:password@hostname:port/database"

🧑‍💻  자연어 → SQL 변환 (Claude 연동)

PG-MCP는 client/claude_cli.py 스크립트를 이용해 자연어 명령을 SQL 쿼리로 변환할 수 있습니다. 예:

python client/claude_cli.py "Show me the top 5 customers by total sales"

🔐 환경 변수 설정

자연어 변환 기능을 사용하려면 다음과 같은 환경 변수 설정이 필요합니다:

# .env 파일 예시
DATABASE_URL=postgresql://username:password@hostname:port/database
ANTHROPIC_API_KEY=your-anthropic-api-key
PG_MCP_URL=http://localhost:8000/sse

🔗 AI 에이전트용 프롬프트 예시

Use the PostgreSQL MCP server to analyze the database. 
Available tools:
- connect: Register a database connection string and get a connection ID
- disconnect: Close a database connection
- pg_query: Execute SQL queries using a connection ID
- pg_explain: Get query execution plans

You can explore schema resources via:
pgmcp://{conn_id}/schemas
pgmcp://{conn_id}/schemas/{schema}/tables
pgmcp://{conn_id}/schemas/{schema}/tables/{table}/columns

---

보안 설계

🛡️ 기본 읽기 전용 모드

PG-MCP는 기본적으로 트랜잭션에서 읽기 전용 모드로 실행되어 데이터 손상 위험이 없습니다.

🔐 안전한 연결 처리

사용자의 연결 정보는 암호화된 연결 ID로만 처리되며, 외부에 노출되지 않습니다.

---

설치 및 실행 방법

🐳 Docker 기반 설치

git clone https://github.com/stuzero/pg-mcp.git
cd pg-mcp
docker-compose up -d

💻 수동 설치 (Python 가상 환경)

git clone https://github.com/stuzero/pg-mcp.git
cd pg-mcp
python -m venv .venv
source .venv/bin/activate  # Windows는 .venv\\Scripts\\activate
uv sync --frozen
python -m server.app

---

확장성과 커뮤니티 참여

🛠️ 확장 기능 추가

PostgreSQL 확장 기능에 대한 추가 정보는 YAML 파일을 통해 자유롭게 확장 가능합니다.

🤝 GitHub 기여

기능 개선, 버그 수정, 문서화 등 누구나 기여할 수 있으며, 프로젝트는 오픈소스로 운영됩니다.

---

아키텍처 구성

🏗️ 핵심 기술 스택

• MCP (Model Context Protocol): 데이터 탐색 프로토콜
• FastMCP: Python 기반 MCP 구현
• asyncpg: 비동기 PostgreSQL 클라이언트
• YAML: 확장 정보 구성

---

결론

PG-MCP는 PostgreSQL 데이터베이스를 AI가 이해하고 활용하는 방식을 혁신하는 솔루션입니다. 데이터 구조의 이해, 쿼리 실행, 확장 정보까지 폭넓게 지원하며 AI 에이전트와의 통합에도 최적화되어 있습니다. 데이터 기반 시스템을 더 똑똑하게 만들고 싶다면 PG-MCP는 훌륭한 선택이 될 것입니다.

---

출처

https://github.com/stuzero/pg-mcp

GitHub - stuzero/pg-mcp