간단한 PostgreSQL MCP 서버

MCP 서버를 직접 구축하려는 분들을 위한 템플릿 프로젝트입니다. 이해하고 수정하기 매우 쉽도록 디자인했습니다. 코드는 간단하고 MCP 문서도 첨부되어 있어 빠르게 익힐 수 있습니다.

MCP란 무엇인가요?

TL;DR - AI를 위한 플러그인을 작성하는 방법입니다.

모델 컨텍스트 프로토콜(MCP)은 LLM이 외부 도구 및 데이터와 상호 작용하는 표준 방식입니다. 간단히 말해서:

• 도구를 사용하면 LLM이 명령(예: 데이터베이스 쿼리 실행)을 실행할 수 있습니다.
• 리소스 는 대화에 첨부할 수 있는 데이터입니다(프롬프트에 파일을 첨부하는 것과 같음).
• 프롬프트는 일관된 LLM 지침을 생성하는 템플릿입니다.

특징

이 PostgreSQL MCP 서버는 다음을 구현합니다.

1. 도구
   • execute_query - 데이터베이스에 대해 SQL 쿼리를 실행합니다.
   • test_connection - 데이터베이스 연결이 작동하는지 확인합니다.
2. 자원
   • db://tables - 스키마의 모든 테이블 목록
   • db://tables/{table_name} - 특정 테이블에 대한 스키마 정보
   • db://schema - 데이터베이스의 모든 테이블에 대한 전체 스키마 정보
3. 프롬프트
   • 쿼리 생성 템플릿
   • 분석 쿼리 빌더
   • 이 저장소의 템플릿을 기반으로

필수 조건

• 파이썬 3.8 이상
• uv - 최신 Python 패키지 관리자 및 설치 프로그램
• npx(Node.js에 포함됨)
• 연결할 수 있는 PostgreSQL 데이터베이스

빠른 설정

1. 가상 환경을 만들고 종속성을 설치합니다.지엑스피1
2. MCP Inspector로 서버를 실행합니다.
   # Replace with YOUR actual database credentials npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://username:password@hostname:port/database -e SCHEMA=public

   참고: npx를 처음 실행하는 경우 설치를 승인하라는 메시지가 표시됩니다. 계속하려면 'y'를 입력하세요.

   이 명령을 실행하면 브라우저에 MCP Inspector 인터페이스가 실행됩니다. 다음과 같은 메시지가 표시됩니다.
   MCP Inspector is up and running at http://localhost:5173
   브라우저가 자동으로 열리지 않으면 URL을 복사하여 브라우저에 붙여넣으세요. 다음과 같은 화면이 표시됩니다.
3. 검사기 사용:
   • 인터페이스에서 "연결" 버튼을 클릭합니다(왼쪽 하단 콘솔에 오류 메시지가 없는 경우)
   • 사용 가능한 기능을 보려면 "도구", "리소스" 및 "프롬프트" 탭을 탐색하세요.
   • 나열된 명령을 클릭하거나 리소스 이름을 입력하여 리소스와 프롬프트를 검색해 보세요.
   • 인터페이스를 사용하면 쿼리를 테스트하고 MCP 서버가 어떻게 응답하는지 확인할 수 있습니다.
4. 공식 문서를 살펴보세요공식 서버 개발자 가이드: https://modelcontextprotocol.io/quickstart/server검사기에 대한 자세한 내용: https://modelcontextprotocol.io/docs/tools/inspector

AI 도구를 서버에 연결하세요

MCP 구성 파일을 생성하여 AI 어시스턴트에 대한 MCP 서버를 구성할 수 있습니다.

또는 포함된 스크립트를 사용하여 이 구성 파일을 생성할 수 있습니다.

메시지가 표시되면 PostgreSQL DSN과 스키마 이름을 입력합니다.

사용 방법

이제 자연어로 데이터에 대한 질문을 LLM에 질문할 수 있습니다.

• "내 데이터베이스에는 어떤 테이블이 있나요?"
• "생성일 기준 상위 5명의 사용자를 보여주세요"
• "주별 주소 계산"

테스트를 위해 Claude Desktop은 기본적으로 MCP를 지원하며 모든 기능(도구, 리소스, 프롬프트)을 바로 사용할 수 있습니다.

예제 데이터베이스(선택 사항)

준비된 데이터베이스가 없거나 연결 문제가 발생하는 경우 포함된 예제 데이터베이스를 사용할 수 있습니다.

이 스크립트는 샘플 사용자 및 주소 테이블이 미리 채워진 PostgreSQL 데이터베이스가 있는 Docker 컨테이너를 생성합니다. 실행 후 다음을 사용하여 연결할 수 있습니다.

다음 단계

이 프로젝트를 자체 MCP 서버로 확장하려면:

1. /src 아래에 새 디렉토리를 만듭니다(예: /src/my-new-mcp ).
2. PostgreSQL 예제를 따라 MCP 서버를 구현하세요.
3. pyproject.toml 에 새 MCP를 추가합니다.

그런 다음 다음을 사용하여 새 MCP를 실행할 수 있습니다.

선적 서류 비치

• 쉬운 LLM 개발을 위한 MCP 문서 포함
• https://modelcontextprotocol.io/tutorials/building-mcp-with-llms 의 접근 방식을 기반으로 합니다.

보안

이 프로젝트는 개발자들이 직접 MCP 서버를 만들 수 있도록 지원하는 실험적인 프로젝트입니다. 시도했을 때 서버가 즉시 종료되지 않도록 최소한의 조치만 취했지만, 이 도구를 사용하면 SQL 인젝션을 실행하기가 매우 쉬우니 주의하세요. 서버는 쿼리가 SELECT로 시작하는지 확인하지만, 그 이상은 보장되지 않습니다. 요약: 개발자가 아니고 유료 고객이 없는 경우가 아니면 실제 운영 환경에서는 실행하지 마세요.

특허

MIT