Postgres Analytics MCP Server

AI 어시스턴트(Claude, Cursor 및 기타 MCP 호환 클라이언트)가 PostgreSQL 데이터베이스를 안전하게 검사하고 쿼리할 수 있게 해주는 Model Context Protocol(MCP) 서버입니다 - 읽기 전용 강제, 행/시간 초과 제한, 전체 감사 로깅을 갖추고 있습니다.

간단한 질문에 답하기 위해 만들어졌습니다: AI 에이전트가 아무것도 망가뜨릴 능력 없이 실제 데이터베이스를 다루게 하려면 어떻게 해야 할까요?

기능

연결되면 AI 클라이언트는 다음과 같은 질문을 할 수 있습니다:

• "내 데이터베이스에 어떤 테이블이 있나요?"

• "가장 최근 주문 10개를 보여주세요."

• "이 쿼리가 왜 느린가요?"

• "어떤 테이블에 인덱스가 없나요?"

서버는 MCP를 통해 5개의 도구를 제공합니다:

Related MCP server: PostgreSQL MCP Server

존재 이유

기업들은 점점 더 AI 에이전트를 내부 시스템(데이터베이스, Kubernetes, API)에 연결하고 있으며, 어려운 부분은 이를 안전하게 수행하는 것입니다. 이 프로젝트는 그에 대한 작고 구체적인 예입니다: AI 클라이언트와 프로덕션 스타일 데이터베이스 사이의 보호된 브리지입니다.

설계 결정

기본적으로 이중으로 읽기 전용: 모든 쿼리는 차단 목록에 대해 검증되며 SELECT, WITH 또는 EXPLAIN으로 시작해야 합니다. 데이터베이스 연결 자체도 두 번째 방어선으로 읽기 전용 모드로 열립니다.

행 제한 및 쿼리 시간 초과: 모든 쿼리는 구성 가능한 행 제한과 문 시간 초과로 제한되어 무제한 데이터를 반환하거나 서버를 중단시킬 수 없습니다.

인증은 채팅이 아닌 프로세스 환경에 있습니다: API 키는 MCP 클라이언트 구성을 통해 환경 변수로 설정되므로 AI 모델이 이를 직접 보거나 처리하지 않습니다.

감사 로깅: 모든 도구 호출은 타임스탬프, 도구 이름, 인수 및 결과와 함께 기록됩니다.

설정

요구 사항: Python 3.11+, PostgreSQL

1. 가상 환경을 만들고 종속성을 설치합니다: python -m venv venv venv\Scripts\Activate.ps1 pip install -r requirements.txt

2. 데이터베이스를 만들고 샘플 스키마를 로드합니다: psql -U postgres -c "CREATE DATABASE sampledb;" psql -U postgres -d sampledb -f seed.sql

3. .env.example을 .env로 복사하고 자신의 값으로 채웁니다.

4. 직접 실행하여 정상 동작을 확인합니다: python -m server.main

Claude Desktop에 연결

claude_desktop_config.json에 추가합니다 (Claude Desktop -> Settings -> Developer -> Edit Config):

"mcpServers": {
  "postgres-analytics": {
    "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
    "args": ["-m", "server.main"],
    "env": {
      "PYTHONPATH": "C:\\path\\to\\project",
      "MCP_API_KEY": "same-value-as-in-.env"
    }
  }
}

기술 스택

Python, PostgreSQL, MCP Python SDK, psycopg2