PostgreSQL 전체 액세스 MCP 서버

PostgreSQL 데이터베이스에 대한 완전한 읽기-쓰기 권한을 제공하는 강력한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 읽기 전용 공식 MCP PostgreSQL 서버와 달리, 이 향상된 구현을 통해 대용량 언어 모델(LLM)은 적절한 트랜잭션 관리 및 보안 제어를 통해 데이터베이스 콘텐츠를 쿼리하고 수정할 수 있습니다.

목차

• 특징
  • 전체 읽기-쓰기 액세스
  • 풍부한 스키마 정보
  • 고급 안전 제어
• 도구
  • 실행_쿼리
  • 실행_dml_ddl_dcl_tcl
  • 실행_커밋
  • 실행_롤백
  • 리스트_테이블
  • 설명_테이블
• 자원
• Claude Desktop과 함께 사용
  • Claude 데스크톱 통합
  • 중요: 안전을 위해 "한 번 허용" 사용
• 환경 변수
• Claude를 사용하여 전체 데이터베이스 액세스 사용
• 보안 고려 사항
  • 데이터베이스 사용자 권한
  • 안전한 사용을 위한 모범 사례
• 도커
• 특허
• 공식 PostgreSQL MCP 서버와의 비교

🌟 특징

전체 읽기-쓰기 액세스

• DML 작업(INSERT, UPDATE, DELETE)을 안전하게 실행합니다.
• DDL을 사용하여 데이터베이스 객체를 생성, 변경 및 관리합니다.
• 명시적 커밋을 통한 트랜잭션 관리
• 안전 시간 초과 및 자동 롤백 보호

풍부한 스키마 정보

• 자세한 열 메타데이터(데이터 유형, 설명, 최대 길이, Null 허용 여부)
• 기본 키 식별
• 외래 키 관계
• 유형 및 고유성 플래그가 포함된 인덱스 정보
• 테이블 행 개수 추정
• 표 및 열 설명(사용 가능한 경우)

고급 안전 제어

• SQL 쿼리 분류(DQL, DML, DDL, DCL, TCL)
• 안전한 쿼리에 대한 강제 읽기 전용 실행
• 모든 작업은 격리된 트랜잭션으로 실행됩니다.
• 자동 거래 시간 초과 모니터링
• 구성 가능한 안전 한계
• 명시적 사용자 확인을 통한 2단계 트랜잭션 커밋 프로세스

🔧 도구

• 실행_쿼리
  • 읽기 전용 SQL 쿼리(SELECT 문) 실행
  • 입력: sql (문자열): 실행할 SQL 쿼리
  • 모든 쿼리는 READ ONLY 트랜잭션 내에서 실행됩니다.
  • 결과에는 실행 시간 측정 항목과 필드 정보가 포함됩니다.
• 실행_dml_ddl_dcl_tcl
  • 데이터 수정 작업(INSERT, UPDATE, DELETE) 또는 스키마 변경(CREATE, ALTER, DROP)을 실행합니다.
  • 입력: sql (문자열): 실행할 SQL 문
  • 구성 가능한 시간 초과로 트랜잭션에 자동으로 래핑됨
  • 명시적 커밋에 대한 트랜잭션 ID를 반환합니다.
  • 중요한 보안 기능 : 대화는 실행 후 종료되므로 사용자는 커밋 또는 롤백을 결정하기 전에 결과를 검토할 수 있습니다.
• 실행_커밋
  • ID로 트랜잭션을 명시적으로 커밋합니다.
  • 입력: transaction_id (문자열): 커밋할 트랜잭션의 ID
  • 커밋 또는 롤백 후 정리를 안전하게 처리합니다.
  • 데이터베이스에 변경 사항을 영구적으로 적용합니다.
• 실행_롤백
  • ID로 트랜잭션을 명시적으로 롤백합니다.
  • 입력: transaction_id (문자열): 롤백할 트랜잭션의 ID
  • 모든 변경 사항을 안전하게 삭제하고 리소스를 정리합니다.
  • 변경 사항을 검토하고 적용하지 않기로 결정할 때 유용합니다.
• 리스트_테이블
  • 데이터베이스의 모든 테이블에 대한 포괄적인 목록을 얻으세요
  • 열 개수와 테이블 설명이 포함됩니다.
  • 입력 매개변수가 필요하지 않습니다
• 설명_테이블
  • 특정 테이블 구조에 대한 자세한 정보를 얻으세요
  • 입력: table_name (문자열): 설명할 테이블의 이름
  • 기본 키, 외래 키, 인덱스 및 열 세부 정보를 포함한 전체 스키마 정보를 반환합니다.

📊 리소스

서버는 데이터베이스 테이블에 대한 향상된 스키마 정보를 제공합니다.

• 테이블 스키마 ( postgres://<host>/<table>/schema )
  • 각 테이블에 대한 자세한 JSON 스키마 정보
  • 전체 열 메타데이터, 기본 키 및 제약 조건이 포함됩니다.
  • 데이터베이스 메타데이터에서 자동으로 검색됨

🚀 Claude Desktop과 함께 사용

Claude 데스크톱 통합

Claude Desktop과 함께 이 서버를 사용하려면 다음 단계를 따르세요.

1. 먼저, 시스템에 Node.js가 설치되어 있는지 확인하세요.
2. npx를 사용하여 패키지를 설치하거나 프로젝트에 추가하세요.
3. claude_desktop_config.json 편집하여 Claude Desktop을 구성합니다(macOS에서는 일반적으로 ~/Library/Application Support/Claude/ 에 있음):

지엑스피1

4. 데이터베이스 연결 문자열을 실제 PostgreSQL 연결 세부 정보로 바꾸세요.
5. Claude Desktop을 완전히 다시 시작하세요

중요: 안전을 위해 "한 번 허용" 사용

Claude가 데이터베이스에 변경 사항을 적용하려고 하면 Claude Desktop에서 승인을 요청합니다.

SQL 변경 사항을 승인하기 전에 항상 주의 깊게 검토하세요!

안전을 위한 모범 사례:

• 커밋 작업의 경우 항상 "한 번 허용"(항상 허용 아님)을 클릭합니다.
• 승인하기 전에 거래 SQL을 주의 깊게 검토하세요.
• 권한이 제한된 데이터베이스 사용자를 사용하는 것을 고려하세요
• 가능하다면 이 서버를 처음 시도할 때 테스트 데이터베이스를 사용하세요.

"한 번만 허용" 방식을 사용하면 필요할 때 Claude가 데이터 관리 작업을 지원하는 동시에 원치 않는 데이터베이스 변경을 방지하기 위한 완벽한 제어가 가능합니다.

⚙️ 환경 변수

Claude Desktop 구성에서 환경 변수를 사용하여 서버 동작을 사용자 지정할 수 있습니다.

주요 환경 변수:

• TRANSACTION_TIMEOUT_MS : 트랜잭션 시간 초과(밀리초) (기본값: 15000)
  • 거래에 더 많은 시간이 필요한 경우 이것을 늘리십시오.
  • 이 시간을 초과하는 거래는 안전을 위해 자동으로 롤백됩니다.
• MAX_CONCURRENT_TRANSACTIONS : 최대 동시 트랜잭션 수(기본값: 10)
  • 보다 보수적인 작업을 위해 이 숫자를 낮추십시오.
  • 값이 높을수록 동시에 더 많은 쓰기 작업이 가능합니다.
• ENABLE_TRANSACTION_MONITOR : 트랜잭션 모니터를 활성화/비활성화합니다("true" 또는 "false", 기본값: "true")
  • 중단된 거래를 모니터링하고 자동으로 롤백합니다.
  • 거의 비활성화할 필요가 없습니다
• PG_STATEMENT_TIMEOUT_MS : SQL 쿼리 실행 시간 초과(ms) (기본값: 30000)
  • 단일 SQL 문이 실행될 수 있는 시간을 제한합니다.
  • 폭주하는 쿼리를 방지하기 위한 중요한 보안 기능
• PG_MAX_CONNECTIONS : 최대 PostgreSQL 연결 수(기본값: 20)
  • 데이터베이스 연결 한도 내에 머무르는 것이 중요합니다.
• MONITOR_INTERVAL_MS : 중단된 거래를 확인할 빈도(기본값: 5000)
  • 일반적으로 조정이 필요하지 않습니다

🔄 Claude를 사용하여 전체 데이터베이스 액세스 사용

이 서버를 통해 Claude는 귀하의 승인 하에 PostgreSQL 데이터베이스를 읽고 쓸 수 있습니다. 다음은 몇 가지 대화 흐름 예시입니다.

예: 새 테이블 만들기 및 데이터 추가

당신: "ID, 이름, 가격, 재고에 대한 열이 있는 새로운 제품 테이블이 필요합니다"

Claude: 데이터베이스를 분석하고 쿼리를 생성합니다.

Claude Desktop에서 이 작업을 승인하라는 메시지가 표시됩니다.

귀하: 검토 후 "한 번 허용"을 클릭하세요.

클로드: "제품 테이블을 만들었습니다. 샘플 데이터를 추가할까요?"

당신: "네, 샘플 상품 5개를 추가해주세요"

Claude: INSERT 문을 생성하고 승인을 요청합니다. "한 번 허용"을 사용하여 검토하고 승인합니다.

예: 안전한 쿼리를 사용한 데이터 분석

당신: "가격별로 제가 가장 좋아하는 제품 3가지는 뭐예요?"

Claude: 읽기 전용 쿼리를 자동으로 실행합니다. 결과를 보여줍니다.

안전 워크플로

가장 중요한 안전 기능은 데이터베이스를 수정하는 모든 작업에 대해 2단계 접근 방식을 적용한다는 것입니다.

1. Claude는 귀하의 요청을 분석하고 SQL을 준비합니다.
2. 읽기 전용 작업(SELECT)의 경우 Claude는 자동으로 실행합니다.
3. 쓰기 작업(INSERT, UPDATE, DELETE, CREATE 등)의 경우:
   • Claude는 트랜잭션에서 SQL을 실행하고 대화를 종료합니다.
   • 결과를 검토합니다
   • 새로운 대화에서 "예"로 응답하면 커밋하고 "아니요"로 응답하면 롤백합니다.
   • Claude Desktop은 변경되는 내용을 정확히 보여주고 권한을 요청합니다.
   • 특정 작업을 허용하려면 "한 번 허용"을 클릭합니다.
   • Claude는 작업을 실행하고 결과를 반환합니다.

이렇게 하면 변경 사항이 데이터베이스에 영구적으로 적용되기 전에 변경 사항을 확인할 수 있는 여러 가지 기회가 제공됩니다.

⚠️ 보안 고려 사항

Claude를 쓰기 액세스 권한으로 데이터베이스에 연결하는 경우:

데이터베이스 사용자 권한

중요: 적절한 권한이 있는 전담 데이터베이스 사용자를 만드세요.

안전한 사용을 위한 모범 사례

1. 항상 "한 번 허용"을 사용하여 각 쓰기 작업을 검토하세요.
   • 데이터베이스 수정에 대해 "항상 허용"을 선택하지 마십시오.
   • SQL을 주의 깊게 검토할 시간을 가지세요
2. 이 도구를 처음 탐색할 때 테스트 데이터베이스에 연결하세요.
   • 초기 테스트를 위해 데이터베이스 복사본/백업을 사용하는 것을 고려하세요
3. 데이터베이스 사용자 권한을 필요한 것으로만 제한합니다.
   • 슈퍼유저나 관리자 계정 사용을 피하세요
   • 가능한 경우 테이블별 권한 부여
4. 광범위하게 사용하기 전에 데이터베이스 백업을 구현하세요
5. LLM에 노출되어서는 안 되는 민감한 데이터는 절대 공유하지 마세요.
6. 승인하기 전에 모든 SQL 작업을 확인하세요 .
   • 테이블 이름 확인
   • 열 이름과 데이터 확인
   • WHERE 절이 적절한지 확인하세요
   • 적절한 거래 처리를 찾으세요

도커

서버는 Docker 컨테이너에서 쉽게 실행할 수 있습니다.

macOS의 Docker의 경우 host.docker.internal을 사용하여 호스트 네트워크에 연결합니다.

📄 라이센스

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여되었습니다.

💡 공식 PostgreSQL MCP 서버와의 비교

작가

작성자: Syahiid Nur Kamil( @syahiidkamil )

저작권 © 2024 샤히드 누르 카밀. 모든 권리 보유.