PostgreSQL MCP 서버

Model Context Protocol(MCP) Python SDK를 사용하는 PostgreSQL MCP 서버 구현 - LLM 애플리케이션과 외부 데이터 소스 간의 원활한 통합을 지원하는 개방형 프로토콜입니다. 이 서버를 통해 AI 에이전트는 표준화된 인터페이스를 통해 PostgreSQL 데이터베이스와 상호 작용할 수 있습니다.

특징

• 데이터베이스 스키마 나열

• 스키마 내의 테이블 나열

• 테이블 구조를 설명하세요

• 테이블 제약 조건 및 관계 나열

• 외래 키 정보 가져오기

• SQL 쿼리 실행

Related MCP server: PostgreSQL MCP Server

빠른 시작

지엑스피1

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 PostgreSQL MCP 서버를 자동으로 설치하려면:

npx -y @smithery/cli install @gldc/mcp-postgres --client claude

수동 설치

1. 이 저장소를 복제하세요:

git clone <repository-url>
cd mcp-postgres

2. 가상 환경을 만들고 활성화합니다(권장):

python -m venv venv
source venv/bin/activate  # On Windows, use: venv\Scripts\activate

3. 종속성 설치:

pip install -r requirements.txt

용법

1. MCP 서버를 시작합니다.

   # Without a connection string (server starts, DB‑backed tools will return a friendly error)
   python postgres_server.py
   
   # Or set the connection string via environment variable:
   export POSTGRES_CONNECTION_STRING="postgresql://username:password@host:port/database"
   python postgres_server.py
   
   # Or pass it using the --conn flag:
   python postgres_server.py --conn "postgresql://username:password@host:port/database"

2. 서버는 다음과 같은 도구를 제공합니다.

• query : 데이터베이스에 대해 SQL 쿼리를 실행합니다.

• list_schemas : 사용 가능한 모든 스키마를 나열합니다.

• list_tables : 특정 스키마의 모든 테이블을 나열합니다.

• describe_table : 테이블 구조에 대한 자세한 정보를 가져옵니다.

• get_foreign_keys : 테이블에 대한 외래 키 관계를 가져옵니다.

• find_relationships : 테이블에 대한 명시적 관계와 암시적 관계를 모두 검색합니다.

Docker로 실행

이미지 빌드:

docker build -t mcp-postgres .

데이터베이스 연결 없이 컨테이너를 실행합니다(서버는 검사 가능한 상태로 유지됨):

docker run -p 8000:8000 mcp-postgres

POSTGRES_CONNECTION_STRING 제공하여 라이브 PostgreSQL 데이터베이스로 실행합니다.

docker run \
  -e POSTGRES_CONNECTION_STRING="postgresql://username:password@host:5432/database" \
  -p 8000:8000 \
  mcp-postgres

환경 변수를 생략하면 서버는 정상적으로 부팅되고 모든 데이터베이스 지원 도구는 사용자가 연결 문자열을 제공할 때까지 "연결 문자열이 설정되지 않았습니다"라는 친절한 메시지를 반환합니다.

mcp.json을 사용한 구성

이 서버를 MCP 호환 도구(예: Cursor)와 통합하려면 ~/.cursor/mcp.json 에 추가하세요.

{
  "servers": {
    "postgres": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "/path/to/postgres_server.py"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://username:password@host:5432/database?ssl=true"
      }
    }
  }
}

POSTGRES_CONNECTION_STRING 생략하면 서버는 여전히 시작되고 전체적으로 검사할 수 있습니다. 데이터베이스 지원 도구는 변수가 제공될 때까지 단순히 정보성 오류를 반환합니다.

바꾸다:

• /path/to/venv 가상 환경 경로로 지정합니다.

• /path/to/postgres_server.py 는 서버 스크립트에 대한 절대 경로입니다.

보안

• 코드에서 민감한 데이터베이스 자격 증명을 노출하지 마십시오.

• 데이터베이스 연결 문자열에 환경 변수 또는 보안 구성 파일을 사용하세요.

• 더 나은 리소스 관리를 위해 연결 풀링을 사용하는 것을 고려하세요.

• 적절한 액세스 제어 및 사용자 인증을 구현합니다.

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

관련 프로젝트

• MCP 사양

• MCP 파이썬 SDK

• MCP 서버

특허

MIT 라이센스

저작권 (c) 2025 gldc

본 소프트웨어 및 관련 문서 파일(이하 "소프트웨어")의 사본을 취득한 모든 사람에게 소프트웨어를 제한 없이 거래할 수 있는 권한을 무상으로 부여합니다. 여기에는 소프트웨어 사본을 사용, 복사, 수정, 병합, 게시, 배포, 하위 라이선스 및/또는 판매할 수 있는 권한이 포함되나 이에 국한되지 않으며, 소프트웨어가 제공된 사람에게도 이러한 권한을 부여합니다. 단, 다음 조건에 따라야 합니다.

위의 저작권 고지와 본 허가 고지는 소프트웨어의 모든 사본 또는 실질적인 부분에 포함되어야 합니다.

본 소프트웨어는 상품성, 특정 목적 적합성 및 비침해에 대한 보증을 포함하되 이에 국한되지 않는 명시적 또는 묵시적 보증 없이 "있는 그대로" 제공됩니다. 어떠한 경우에도 저작자 또는 저작권자는 본 소프트웨어 또는 본 소프트웨어의 사용 또는 기타 거래와 관련하여 발생하는 계약, 불법 행위 또는 기타 소송을 포함한 모든 청구, 손해 또는 기타 책임에 대해 책임을 지지 않습니다.