모델 컨텍스트 프로토콜 PostgreSQL 서버

이 프로젝트는 PostgreSQL 데이터베이스에 연결되는 모델 컨텍스트 프로토콜(MCP) 서버를 구현합니다. 이를 통해 AI 모델이 표준화된 프로토콜을 통해 데이터베이스와 상호 작용할 수 있습니다.

특징

• 연결 풀링을 사용하여 PostgreSQL 데이터베이스에 연결합니다.
• AI 모델 상호작용을 위한 모델 컨텍스트 프로토콜을 구현합니다.
• 데이터베이스 스키마 정보를 리소스로 제공합니다.
• 재시도 논리를 사용하여 SQL 쿼리를 실행할 수 있습니다.
• 연결 오류를 정상적으로 처리합니다.

필수 조건

• Node.js 20 이상
• PostgreSQL 데이터베이스
• 데이터베이스에 대한 액세스 자격 증명

설치

1. 이 저장소를 복제하세요
2. 종속성 설치:

지엑스피1

구성

서버는 프로젝트 루트 디렉터리의 .env 파일에서 데이터베이스 자격 증명을 읽습니다. DB_CREDENTIALS 환경 변수에 데이터베이스 자격 증명을 JSON 문자열로 추가해야 합니다.

1. 프로젝트 루트에 .env 파일을 만듭니다.

2. 실제 데이터베이스 자격 증명을 사용하여 다음 줄을 추가합니다.

Shell 구성 파일로의 폴백

.env 파일이 없거나 자격 증명 변수를 찾을 수 없는 경우 서버는 다음 순서에 따라 셸 구성 파일에서 자격 증명을 자동으로 찾습니다.

1. ~/.zshrc
2. ~/.bashrc
3. ~/.bash_profile
4. ~/.profile

이 기능은 Cursor MCP 환경처럼 셸 구성 파일이 자동으로 소싱되지 않는 환경에서 특히 유용합니다.

셸 구성 파일에서 자격 증명을 설정하려면 다음을 수행합니다.

1. 다음과 같이 원하는 셸 구성 파일을 엽니다.

2. 실제 데이터베이스 자격 증명을 사용하여 다음 줄을 추가합니다.

.env 파일을 사용할 수 없는 경우 서버는 이러한 자격 증명을 자동으로 감지하고 사용합니다.

사용자 정의 자격 증명 변수

서버를 시작할 때 --credentials-var 플래그를 사용하여 DB_CREDENTIALS 대신 사용자 지정 환경 변수 이름을 사용할 수도 있습니다.

이 경우에는 .env 파일에서 MY_CUSTOM_DB_CREDS 정의해야 합니다.

옵션 결합

필요에 따라 다양한 명령줄 옵션을 결합할 수 있습니다.

용법

MCP 서버를 시작합니다.

로깅 옵션

기본적으로 서버는 자동 모드로 실행되어 오류 메시지만 표시합니다. 모든 로그 메시지를 보려면 verbose 플래그를 사용할 수 있습니다.

또한 짧은 플래그 -v 사용할 수도 있습니다.

서버는 다음을 수행합니다.

1. 데이터베이스 연결 테스트
2. stdio 전송을 사용하여 MCP 서버를 시작합니다.
3. AI 모델의 요청 처리

커서와의 통합

이 서버는 MCP(Model Context Protocol)를 지원하고 Cursor AI와 통합됩니다.

자동 구성

이 프로젝트에는 Cursor 내에서 자동 설정을 위한 미리 구성된 .cursor/mcp.json 파일이 포함되어 있습니다.

수동 구성

이 서버를 Cursor에 수동으로 추가하려면:

1. 커서 설정 → 기능 → MCP로 이동하세요.
2. "+ 새 MCP 서버 추가"를 클릭하세요
3. 다음 세부 정보를 입력하세요.
   • 이름 : Postgres MCP
   • 유형 : stdio
   • 명령어 : node /full/path/to/server.js

Cursor와 MCP 통합에 대한 자세한 내용은 공식 문서를 참조하세요.

사용 가능한 도구

서버는 AI 모델에 다음과 같은 도구를 제공합니다.

• query : 재시도 논리를 사용하여 SQL 쿼리를 실행합니다.

자원

서버는 데이터베이스 테이블을 리소스로 노출하여 AI 모델이 다음을 수행할 수 있도록 합니다.

• 데이터베이스의 모든 테이블 나열
• 각 테이블에 대한 스키마 정보 보기

오류 처리

서버에는 다음이 포함됩니다.

• 연결 재시도 논리
• 자세한 오류 로깅
• 우아한 종료 처리

문제 해결

연결 문제

1. 데이터베이스 연결에 실패했습니다
   • PostgreSQL이 실행 중인지 확인하세요: pg_isready -h localhost -p 5433
   • .env 파일에서 자격 증명이 올바른지 확인하세요.
   • IP 주소가 데이터베이스에 액세스할 수 있는지 확인하세요(pg_hba.conf 확인)
   • 자격 증명을 확인하려면 psql 과 같은 다른 도구를 사용하여 연결을 시도하세요.
2. 환경 변수 문제
   • .env 파일이 프로젝트 루트 디렉토리에 있는지 확인하세요.
   • DB_CREDENTIALS 의 JSON 구조가 유효한지 확인하세요.
   • JSON 문자열에 추가 공백이나 줄 바꿈이 없는지 확인하세요.
   • 테스트 명령어: node -e "console.log(JSON.parse(process.env.DB_CREDENTIALS))" < .env
3. Node.js 버전 문제
   • Node.js 버전을 확인하세요: node -v
   • 이 서버에는 Node.js 20 이상이 필요합니다.
   • 이전 버전을 사용하는 경우 Node.js 20을 설치하세요: nvm install 20 && nvm use 20

커서 통합

1. 커서에 서버가 표시되지 않음
   • .cursor/mcp.json 파일이 존재하고 올바르게 포맷되었는지 확인하세요.
   • 프로젝트별 구성을 감지하려면 Cursor를 다시 시작해 보세요.
   • 오류 메시지가 있는지 커서 로그를 확인하세요.
2. "클라이언트 생성에 실패했습니다" 오류
   • 이는 일반적으로 서버가 시작 중에 충돌했음을 나타냅니다.
   • 자세한 로깅을 사용하여 서버를 수동으로 실행하여 오류를 확인하세요: node server.js -v
   • 커서 환경에서 데이터베이스 자격 증명에 액세스할 수 있는지 확인하세요.
3. 커서에 사용 가능한 도구가 없습니다
   • 서버가 제대로 실행되고 있는지 확인하세요(로그 확인)
   • MCP 도구 패널에서 새로 고침 버튼을 클릭해 보세요.
   • 커서를 다시 시작하고 다시 시도하세요

PostgreSQL 특정 문제

1. 권한 거부 오류
   • 데이터베이스 사용자에게 테이블에 대한 적절한 권한이 있는지 확인하세요.
   • 필요한 권한을 부여해보세요: GRANT SELECT ON ALL TABLES IN SCHEMA public TO username;
2. "관계가 존재하지 않습니다" 오류
   • 테이블이 존재하는지 확인하세요: \dt tablename
   • 올바른 데이터베이스에 연결하고 있는지 확인하세요
   • 사용자가 테이블이 있는 스키마에 액세스할 수 있는지 확인하세요.
3. 성능 문제
   • 큰 쿼리 결과로 인해 지연이 발생할 수 있으므로 LIMIT 절을 추가하는 것이 좋습니다.
   • 데이터베이스에 최적화(인덱스, 진공 청소)가 필요한지 확인하세요.

추가 도움이 필요한 경우 자세한 오류 메시지와 작업 로그를 보려면 자세한 로깅( -v 플래그)을 사용하여 서버를 실행할 수 있습니다.

특허

MIT