간단한 PostgreSQL MCP 서버

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

MCP란 무엇인가요?

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

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

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

특징

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

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

필수 조건

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

빠른 설정

가상 환경을 만들고 종속성을 설치합니다.지엑스피1
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을 복사하여 브라우저에 붙여넣으세요. 다음과 같은 화면이 표시됩니다.
검사기 사용:
- 인터페이스에서 "연결" 버튼을 클릭합니다(왼쪽 하단 콘솔에 오류 메시지가 없는 경우)
- 사용 가능한 기능을 보려면 "도구", "리소스" 및 "프롬프트" 탭을 탐색하세요.
- 나열된 명령을 클릭하거나 리소스 이름을 입력하여 리소스와 프롬프트를 검색해 보세요.
- 인터페이스를 사용하면 쿼리를 테스트하고 MCP 서버가 어떻게 응답하는지 확인할 수 있습니다.
공식 문서를 살펴보세요공식 서버 개발자 가이드: https://modelcontextprotocol.io/quickstart/server검사기에 대한 자세한 내용: https://modelcontextprotocol.io/docs/tools/inspector

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

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

{
   "mcpServers": {
      "postgres": {
         "command": "/path/to/uv",
         "args": [
            "--directory",
            "/path/to/simple-psql-mcp",
            "run",
            "postgres"
         ],
         "env": {
            "DSN": "postgresql://username:password@localhost:5432/my-db",
            "SCHEMA": "public"
         }
      }
   }
}

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

# Make the script executable
chmod +x generate_mcp_config.sh

# Run the configuration generator
./generate_mcp_config.sh

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

사용 방법

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

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

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

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

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

# Make the script executable
chmod +x example-db/create-db.sh

# Run the database setup script
./example-db/create-db.sh

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

npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://postgres:postgres@localhost:5432/user_database -e SCHEMA=public

다음 단계

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

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

[project.scripts]
postgres = "src.postgres:main"
my-new-mcp = "src.my-new-mcp:main"

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

npx @modelcontextprotocol/inspector uv --directory . run my-new-mcp

선적 서류 비치

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

보안

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

특허

MIT

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

PostgreSQL 데이터베이스에 직접 액세스할 수 있는 사용자 지정 MCP 서버를 구축하기 위한 템플릿 프로젝트로, Model Context Protocol을 통해 SQL 쿼리 실행과 스키마 정보 검색이 가능합니다.

Related MCP Servers

db-mcp-tool
wirdes
A
security
A
license
A
quality
A powerful Model Context Protocol (MCP) tool for exploring and managing different types of databases including PostgreSQL, MySQL, and Firestore.
Last updated -
9
3
TypeScript
MIT License
MCP Postgres Server
MadeByNando
-
security
F
license
-
quality
A server implementing the Model Context Protocol (MCP) for Cursor that allows using a PostgreSQL database as storage for model contexts, enabling secure database exploration and querying.
Last updated -
JavaScript
MCP PostgreSQL Server
a21071
-
security
F
license
-
quality
A Model Context Protocol server that enables performing PostgreSQL database operations (create, read, update, delete) on User and Post entities through MCP tools.
Last updated -
TypeScript
PostgreSQL MCP Server
hthuong09
-
security
F
license
-
quality
A Model Context Protocol server that enables interaction with PostgreSQL databases to list tables, retrieve schemas, and execute read-only SQL queries.
Last updated -
16,948
JavaScript

View all related MCP servers

Simple PostgreSQL MCP Server