FastPostgresMCP 🐘⚡️ (모든 기능을 갖춘 다중 DB MCP 서버)
이 프로젝트는 AI 에이전트(예: Cursor, Claude Desktop)가 여러 PostgreSQL 데이터베이스와 상호 작용하고 테이블 나열 및 스키마 검사를 수행할 수 있도록 설계된 매우 빠르고 유형이 안전하며 모든 기능을 갖춘 Model Context Protocol(MCP) 서버를 구현합니다.
Bun, TypeScript, postgres 로 구축되었으며, 견고한 MCP 서버를 구축하기 위한 fastmcp 프레임워크의 고급 기능을 활용합니다.
목적: AI 에이전트를 위한 MCP 서버
이 라이브러리는 코드에 임포트할 수 없습니다 . 독립형 서버 애플리케이션 입니다. 프로세스로 실행하면 MCP 클라이언트(AI 에이전트 등)는 JSON 기반 모델 컨텍스트 프로토콜(v2.0)을 사용하여 통신합니다. 일반적으로 클라이언트 애플리케이션(예: Cursor)에서 관리하는 stdio 연결을 통해 통신합니다.
Related MCP server: pg-mcp
문제 해결 및 개발
테스트를 위한 CLI 사용
패키지에는 MCP 서버를 직접 테스트하기 위한 내장 CLI 명령이 포함되어 있습니다.
지엑스피1
내장된 MCP 검사기로 테스트
MCP Inspector를 사용하여 시각적으로 테스트하고 디버깅할 수도 있습니다.
일반적인 문제
bunx postgres-mcp 실행할 때 다음 오류가 표시되면:
ping 메시지가 뒤따르는 경우 다음을 의미합니다.
MCP 서버가 성공적으로 시작되었습니다.
클라이언트가 성공적으로 연결되었습니다
하지만 클라이언트는 ping 요청만 보내고 기능을 제대로 협상하지 않습니다.
이는 일반적으로 적절한 MCP 클라이언트를 사용해야 함을 나타냅니다. 다음을 시도해 보세요.
bun run cli사용하여 MCP CLI로 테스트설치 섹션에 설명된 대로 Cursor 또는 Claude Desktop에서 MCP 서버 구성
사용자 정의 MCP 클라이언트를 개발하는 경우 기능 협상을 포함하여 MCP 프로토콜을 올바르게 구현했는지 확인하세요.
✨ 핵심 기능
🚀 매우 빠름: Bun과
fastmcp기반으로 구축됨.🔒 Type-Safe: Zod 스키마 검증을 통한 종단 간 TypeScript.
🐘 다중 데이터베이스 지원:
.env에 정의된 여러 PostgreSQL 인스턴스에 연결하고 상호작용을 관리합니다.🛡️ 보안을 고려한 설계:
postgres통한 매개변수화된 쿼리는 SQL 주입을 방지합니다.🔑 선택적 인증: API 키 검증(
fastmcp의authenticate후크)을 사용하여 네트워크 기반 연결(SSE/HTTP)을 보호합니다.📄 MCP 리소스를 통한 데이터베이스 스키마:
테이블 목록:
db://{dbAlias}/schema/tables통해 데이터베이스의 테이블 목록을 가져옵니다.테이블 스키마 검사:
db://{dbAlias}/schema/{tableName}통해 특정 테이블에 대한 자세한 열 정보를 가져옵니다.
💬 향상된 도구 상호작용:
도구 내 로깅: 도구는 자세한 로그를 클라이언트로 다시 보냅니다(
log컨텍스트).진행 상황 보고: 장기 실행 작업은 진행 상황을 보고합니다(
reportProgress컨텍스트).
🧠 세션 인식: 도구 실행 컨텍스트(
session컨텍스트) 내에서 세션 정보에 액세스합니다.📡 이벤트 기반: 연결/세션 이벤트 처리를 위해
server.on및session.on사용합니다.🔧 최신 개발자 경험(DX): 명확한 구성, 직관적인 API,
fastmcp도구를 사용한 간편한 테스트.
포함 사항(fastmcp 기능 활용)
FastMCP서버 코어server.addTool(query_tool,execute_tool,schema_tool및transaction_tool용)server.addResourceTemplate(테이블 나열 및 테이블 스키마 검사용)server.start(stdio포커스 포함,sse/http에 맞게 조정 가능)선택 사항:
authenticate후크(API 키 검증용)도구 실행
context(log,reportProgress,session)매개변수 스키마 검증을 위한 Zod
server.on(연결 로깅용)(잠재적으로) 세션별 논리를 위한
session.on
📋 필수 조건
Bun 설치되었으며 PATH에 있습니다.
PostgreSQL 데이터베이스: 액세스 자격 증명 및 연결. 사용자에게
information_schema쿼리 권한이 필요합니다.
⚙️ 설치
옵션 1: NPM 패키지
npm 패키지는 https://www.npmjs.com/package/postgres-mcp 에서 사용할 수 있습니다.
옵션 2: 저장소 복제
저장소를 복제합니다.
# Replace with your actual repository URL git clone https://github.com/llm-graph/postgres-mcp.git cd postgres-mcp종속성 설치:
bun install
🔑 구성(다중 데이터베이스 및 선택적 인증)
적절한 .env 파일에서 로드된 환경 변수를 통해 구성합니다.
환경 파일을 만듭니다.
프로덕션의 경우:
cp .env.example .env개발용:
cp .env.development.example .env.development
환경 파일 로딩 순서: 서버는 다음 우선순위 순서에 따라 파일에서 환경 변수를 로드합니다.
.env.<NODE_ENV>(예:.env.development,.env.production,.env.staging).env.local(버전 제어되지 않는 로컬 재정의용).env(기본 대체) 이를 통해 다양한 환경에 맞게 다양한 구성이 가능합니다.
데이터베이스 연결과 인증을 정의하려면 환경 파일을 편집하세요 .
DB_ALIASES- 고유한 DB 별칭의 쉼표로 구분된 목록DEFAULT_DB_ALIAS- 도구 호출에서 'dbAlias'가 생략된 경우 기본 별칭각 별칭에 대한 데이터베이스 연결 세부 정보(예:
DB_MAIN_HOST,DB_REPORTING_HOST)선택적 API 키 인증(
ENABLE_AUTH,MCP_API_KEY)
🚀 서버 실행(프로세스로)
Bun을 사용하여 이 서버를 직접 실행하세요. AI 클라이언트(Cursor와 유사)가 일반적으로 이 명령을 실행하고 관리해 줍니다.
옵션 1: 글로벌하게 설치된 패키지 사용
수동으로 실행하려면:
postgres-mcp
옵션 2: 프로젝트에서 패키지 사용
프로젝트에서 실행하려면:
npx postgres-mcp또는 프로그래밍 방식으로 가져오기:
// server.js import { startServer } from 'postgres-mcp'; // Start the MCP server startServer();
옵션 3: 복제된 저장소에서
수동으로 실행하려면(테스트용):
bun run src/index.ts수동 개발 모드:
bun run --watch src/index.ts
fastmcp CLI 도구로 테스트
대화형 터미널:
bunx fastmcp dev src/index.ts웹 UI 검사기:
bunx fastmcp inspect src/index.ts
💻 프로그래밍 API 사용(라이브러리로)
postgres-mcp는 독립형 MCP 서버로 실행하는 것 외에도 Node.js/TypeScript 애플리케이션에서 라이브러리로 프로그래밍 방식으로 사용할 수도 있습니다.
기본 사용법
직접 함수 가져오기
더 간단한 사용 사례에서는 특정 함수를 직접 가져올 수 있습니다.
구성 옵션
프로그래밍 API에 대한 전체 설명서는 docs/programmatic-api.md를 참조하세요.
🔌 AI 클라이언트(Cursor, Claude Desktop)와 연결
AI 에이전트(MCP 클라이언트)를 구성하여 명령/인수 메커니즘을 통해 이 서버 스크립트를 실행하세요 .
커서 AI - 자세한 예
커서 설정/환경 설정을 엽니다(Cmd+, 또는 Ctrl+,).
"확장 프로그램" -> "MCP"로 이동합니다.
"MCP 서버 추가"를 클릭하거나
settings.json편집합니다.다음 JSON 구성을 추가합니다.
// In Cursor's settings.json or MCP configuration UI { "mcpServers": { "postgres-mcp": { // Unique name for Cursor "description": "MCP Server for PostgreSQL DBs (Main, Reporting)", "command": "bunx", // Use 'bun' or provide absolute path: "/Users/your_username/.bun/bin/bun" "args": [ "postgres-mcp" // or // *** ABSOLUTE PATH to your server's entry point *** // "/Users/your_username/projects/postgres-mcp/src/index.ts" / ], "env": { // .env file in project dir is loaded automatically by Bun. // Add overrides or Cursor-specific vars here if needed. }, "enabled": true } } }커서를 저장 하고 다시 시작하거나 "MCP 서버 다시 로드"를 클릭합니다.
커서의 MCP 상태/로그에서 연결을 확인하세요 .
클로드 데스크탑
config.json찾아 편집합니다(경로는 이전 README 참조).args에 절대 경로를 사용하여mcpServers아래에 비슷한 항목을 추가합니다.Claude Desktop을 다시 시작합니다.
🛠️ MCP 기능 공개
인증(선택 사항)
ENABLE_AUTH=true경우MCP_API_KEY와 일치하는X-API-Key헤더를 통해 네트워크 전송(HTTP/SSE)을 보호합니다.stdio연결(Cursor/Claude의 기본값)은 일반적으로 이 검사를 우회합니다.
자원
1. 데이터베이스 테이블 나열
URI 템플릿:
db://{dbAlias}/schema/tables설명: 지정된 데이터베이스 별칭(일반적으로 'public' 스키마에서) 내의 사용자 테이블 이름 목록을 검색합니다.
리소스 정의(
uriTemplate:"db://{dbAlias}/schema/tables"arguments:dbAlias: (문자열, 필수) - 데이터베이스의 별칭(.env에서).
load({ dbAlias }): 데이터베이스에 연결하고information_schema.tables(공개 스키마의 기본 테이블에 대해 필터링, 구현 시 사용자 정의 가능)를 쿼리하고 결과를 JSON 문자열 배열["table1", "table2", ...]로 포맷하고{ text: "..." }반환합니다.
사용 예(AI 프롬프트): "기본 데이터베이스의 테이블을 나열하려면 리소스 db://main/schema/tables 가져옵니다."
2. 테이블 스키마 검사
URI 템플릿:
db://{dbAlias}/schema/{tableName}설명: 특정 테이블에 대한 자세한 스키마 정보(열, 유형, NULL 허용 여부, 기본값)를 제공합니다.
리소스 정의(
uriTemplate:"db://{dbAlias}/schema/{tableName}"arguments:dbAlias: (문자열, 필수) - 데이터베이스 별칭.tableName: (문자열, 필수) - 테이블의 이름입니다.
load({ dbAlias, tableName }): 연결하고, 특정 테이블에 대한information_schema.columns쿼리하고, 열 개체의 JSON 문자열 배열로 포맷하고,{ text: "..." }반환합니다.
사용 예시(AI 프롬프트): " db://reporting/schema/daily_sales 리소스를 설명하세요."
응답 내용 예(JSON 문자열):
도구
도구는 context 객체( log , reportProgress , session )를 수신합니다.
1. query_tool
읽기 전용 SQL 쿼리를 실행합니다.
설명: 실행 로깅/진행 상황을 기록하여 읽기 전용 SQL을 안전하게 실행하고 결과를 얻습니다.
매개변수:
statement(문자열),params(배열, opt),dbAlias(문자열, opt).컨텍스트 사용:
log.info/debug, 선택적reportProgress, 액세스session.반환: 행 배열의 JSON 문자열.
요청 예시:
응답 내용 예(JSON 문자열):
2. execute_tool
데이터를 수정하는 SQL 문을 실행합니다.
설명: 실행 로깅을 통해 데이터를 수정하는 SQL을 안전하게 실행합니다.
매개변수:
statement(문자열),params(배열, opt),dbAlias(문자열, opt).컨텍스트 사용:
log.info/debug,session에 접근합니다.반환값: 영향을 받는 행을 나타내는 문자열입니다.
요청 예시:
응답 내용 예시(문자열):
3. schema_tool
특정 테이블에 대한 자세한 스키마 정보를 검색합니다.
설명: 데이터베이스 테이블에 대한 열 정의와 세부 정보를 가져옵니다.
매개변수:
tableName(문자열),dbAlias(문자열, opt).컨텍스트 사용:
log.info, 액세스session.반환: 열 정보 객체의 JSON 문자열 배열입니다.
요청 예시:
응답 내용 예(JSON 문자열):
4. transaction_tool
여러 SQL 문을 원자적으로 실행합니다.
설명: 단계별 로깅/진행 상황을 기록하여 트랜잭션에서 SQL 시퀀스를 실행합니다.
매개변수:
operations({statement, params}의 배열),dbAlias(문자열, opt).컨텍스트 사용:
log.info/debug/error,reportProgress, accesssession.반환: 성공/실패를 요약한 JSON 문자열:
{"success": true, "results": [...]}또는{"success": false, "error": ..., "failedOperationIndex": ...}.
요청 예시:
성공 응답 콘텐츠 예시(JSON 문자열):
오류 응답 내용 예(JSON 문자열):
서버 및 세션 이벤트
클라이언트 연결을 로깅하려면
server.on('connect'/'disconnect')사용합니다.필요한 경우 보다 세부적인 세션 이벤트 처리를 위해
session.on(...)사용할 수 있습니다.
🔒 보안 고려 사항
SQL 주입: 매개변수화된 쿼리를 통해 완화됩니다. 직접적인 입력 연결은 없습니다.
데이터베이스 권한: 중요. 각
DB_<ALIAS>_USER에 최소한의 권한을 할당하세요. 여기에는 스키마/테이블 목록 리소스에 대한information_schema읽기 권한이 포함됩니다.SSL/TLS: 프로덕션에 필수 (
DB_<ALIAS>_SSL=require또는 stricter).비밀 관리:
.env파일을 보호하세요(.gitignore파일에 추가). 운영 환경(Vault, Doppler, 클라우드 비밀)에 안전한 비밀 관리를 사용하세요.인증 범위:
authenticate후크는 주로 네트워크 전송을 보호합니다.stdio보안은 실행 환경에 따라 달라집니다.데이터 민감성: 연결/도구를 통해 접근 가능한 데이터를 파악하세요.
리소스 쿼리: 테이블(
information_schema.tables) 및 스키마(information_schema.columns)를 나열하는 데 사용되는 쿼리는 일반적으로 안전하지만 데이터베이스 권한에 의존합니다. 구성된 사용자에게 적절한 읽기 권한이 있는지 확인하십시오. 보안 또는 명확성을 위해 필요한 경우 테이블 나열 쿼리(예: 스키마 필터링)를 사용자 정의하십시오.
📜 라이센스
이 프로젝트는 MIT 라이선스 에 따라 라이선스가 부여됩니다. 자세한 내용은 라이선스 파일을 참조하세요.
📋 변경 사항
1.0.0
최초 출시
PostgreSQL을 위한 모든 기능을 갖춘 MCP 서버
다중 데이터베이스 연결 지원
쿼리, 실행, 스키마 검사 및 트랜잭션을 위한 도구
스키마 내성을 위한 리소스
포괄적인 문서 및 예제