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 연결을 통해 통신합니다.

문제 해결 및 개발

테스트를 위한 CLI 사용

패키지에는 MCP 서버를 직접 테스트하기 위한 내장 CLI 명령이 포함되어 있습니다.

지엑스피1

내장된 MCP 검사기로 테스트

MCP Inspector를 사용하여 시각적으로 테스트하고 디버깅할 수도 있습니다.

# From the project repository:
bun run inspect

일반적인 문제

bunx postgres-mcp 실행할 때 다음 오류가 표시되면:

FastPostgresMCP started
[warning] FastMCP could not infer client capabilities

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 (v1.0 이상 권장): 설치되었으며 PATH에 있습니다.
PostgreSQL 데이터베이스: 액세스 자격 증명 및 연결. 사용자에게 information_schema 쿼리 권한이 필요합니다.

⚙️ 설치

옵션 1: NPM 패키지

# Install globally
npm install -g postgres-mcp

# Or install locally in your project
npm install postgres-mcp

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 )

# Example .env file - Key Variables

# REQUIRED: Comma-separated list of unique DB aliases
DB_ALIASES=main,reporting

# REQUIRED: Default alias if 'dbAlias' is omitted in tool calls
DEFAULT_DB_ALIAS=main

# OPTIONAL: Enable API Key auth (primarily for network transports)
ENABLE_AUTH=false
MCP_API_KEY=your_super_secret_api_key_here # CHANGE THIS

# Define DB connection details for each alias (DB_MAIN_*, DB_REPORTING_*, etc.)
DB_MAIN_HOST=localhost
DB_MAIN_PORT=5432
DB_MAIN_NAME=app_prod_db
DB_MAIN_USER=app_user
DB_MAIN_PASSWORD=app_secret_password
DB_MAIN_SSL=disable

# Alternative: Use connection URLs
# DB_MAIN_URL=postgres://user:password@localhost:5432/database?sslmode=require

# --- Optional: Server Logging Level ---
# LOG_LEVEL=info # debug, info, warn, error (defaults to info)

🚀 서버 실행(프로세스로)

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 애플리케이션에서 라이브러리로 프로그래밍 방식으로 사용할 수도 있습니다.

기본 사용법

import { createPostgresMcp } from 'postgres-mcp';

// Create the PostgresMcp instance
const postgresMcp = createPostgresMcp();

// Start the server
postgresMcp.start();

// Direct database operations
const results = await postgresMcp.executeQuery(
  'SELECT * FROM users WHERE role = $1',
  ['admin'],
  'main' // optional database alias
);

// When done, stop the server and close connections
await postgresMcp.stop();

직접 함수 가져오기

더 간단한 사용 사례에서는 특정 함수를 직접 가져올 수 있습니다.

import { 
  initConnections, 
  closeConnections, 
  executeQuery, 
  executeCommand, 
  executeTransaction, 
  getTableSchema,
  getAllTableSchemas
} from 'postgres-mcp';

// Configure database connections
const dbConfigs = {
  main: {
    host: 'localhost',
    port: 5432,
    database: 'my_db',
    user: 'db_user',
    password: 'db_password'
  }
};

// Initialize connections
initConnections(dbConfigs);

// Execute a query
const results = await executeQuery(
  'SELECT * FROM users WHERE role = $1',
  ['admin'],
  'main'
);

// Get schema for a single table
const schema = await getTableSchema('users', 'main');

// Get schema for all tables in the database
const allSchemas = await getAllTableSchemas('main');

// Close connections when done
await closeConnections();

구성 옵션

const postgresMcp = createPostgresMcp({
  // Custom database configurations (override .env)
  databaseConfigs: {
    main: {
      host: 'localhost',
      port: 5432,
      database: 'app_db',
      user: 'app_user',
      password: 'password',
      ssl: 'disable'
    }
  },
  // Server configuration
  serverConfig: {
    name: 'Custom PostgresMCP',
    defaultDbAlias: 'main'
  },
  // Transport options: 'stdio', 'sse', or 'http'
  transport: 'http',
  port: 3456
});

프로그래밍 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' 스키마에서) 내의 사용자 테이블 이름 목록을 검색합니다.
리소스 정의( addResourceTemplate ):
- 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 허용 여부, 기본값)를 제공합니다.
리소스 정의( addResourceTemplate ):
- uriTemplate : "db://{dbAlias}/schema/{tableName}"
- arguments :
  - dbAlias : (문자열, 필수) - 데이터베이스 별칭.
  - tableName : (문자열, 필수) - 테이블의 이름입니다.
- load({ dbAlias, tableName }) : 연결하고, 특정 테이블에 대한 information_schema.columns 쿼리하고, 열 개체의 JSON 문자열 배열로 포맷하고, { text: "..." } 반환합니다.

사용 예시(AI 프롬프트): " db://reporting/schema/daily_sales 리소스를 설명하세요."

응답 내용 예(JSON 문자열):

"[{\"column_name\":\"session_id\",\"data_type\":\"uuid\",\"is_nullable\":\"NO\",\"column_default\":\"gen_random_uuid()\"},{\"column_name\":\"user_id\",\"data_type\":\"integer\",\"is_nullable\":\"NO\",\"column_default\":null},{\"column_name\":\"created_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":\"now()\"},{\"column_name\":\"expires_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":null}]"

도구

도구는 context 객체( log , reportProgress , session )를 수신합니다.

1. `query_tool`

읽기 전용 SQL 쿼리를 실행합니다.

설명: 실행 로깅/진행 상황을 기록하여 읽기 전용 SQL을 안전하게 실행하고 결과를 얻습니다.
매개변수: statement (문자열), params (배열, opt), dbAlias (문자열, opt).
컨텍스트 사용: log.info/debug , 선택적 reportProgress , 액세스 session .
반환: 행 배열의 JSON 문자열.

요청 예시:

{
  "tool_name": "query_tool",
  "arguments": {
    "statement": "SELECT product_id, name, price FROM products WHERE category = $1 AND price < $2 ORDER BY name LIMIT 10",
    "params": ["electronics", 500],
    "dbAlias": "main"
  }
}

응답 내용 예(JSON 문자열):

"[{\"product_id\":123,\"name\":\"Example Gadget\",\"price\":499.99},{\"product_id\":456,\"name\":\"Another Device\",\"price\":350.00}]"

2. `execute_tool`

데이터를 수정하는 SQL 문을 실행합니다.

설명: 실행 로깅을 통해 데이터를 수정하는 SQL을 안전하게 실행합니다.
매개변수: statement (문자열), params (배열, opt), dbAlias (문자열, opt).
컨텍스트 사용: log.info/debug , session 에 접근합니다.
반환값: 영향을 받는 행을 나타내는 문자열입니다.

요청 예시:

{
  "tool_name": "execute_tool",
  "arguments": {
    "statement": "UPDATE users SET last_login = NOW() WHERE user_id = $1",
    "params": [54321]
    // dbAlias omitted, uses DEFAULT_DB_ALIAS
  }
}

응답 내용 예시(문자열):

"Rows affected: 1"

3. `schema_tool`

특정 테이블에 대한 자세한 스키마 정보를 검색합니다.

설명: 데이터베이스 테이블에 대한 열 정의와 세부 정보를 가져옵니다.
매개변수: tableName (문자열), dbAlias (문자열, opt).
컨텍스트 사용: log.info , 액세스 session .
반환: 열 정보 객체의 JSON 문자열 배열입니다.

요청 예시:

{
  "tool_name": "schema_tool",
  "arguments": {
    "tableName": "user_sessions",
    "dbAlias": "main"
  }
}

응답 내용 예(JSON 문자열):

"[{\"column_name\":\"session_id\",\"data_type\":\"uuid\",\"is_nullable\":\"NO\",\"column_default\":\"gen_random_uuid()\"},{\"column_name\":\"user_id\",\"data_type\":\"integer\",\"is_nullable\":\"NO\",\"column_default\":null},{\"column_name\":\"created_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":\"now()\"},{\"column_name\":\"expires_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":null}]"

4. `transaction_tool`

여러 SQL 문을 원자적으로 실행합니다.

설명: 단계별 로깅/진행 상황을 기록하여 트랜잭션에서 SQL 시퀀스를 실행합니다.
매개변수: operations ({statement, params}의 배열), dbAlias (문자열, opt).
컨텍스트 사용: log.info/debug/error , reportProgress , access session .
반환: 성공/실패를 요약한 JSON 문자열: {"success": true, "results": [...]} 또는 {"success": false, "error": ..., "failedOperationIndex": ...} .

요청 예시:

{
  "tool_name": "transaction_tool",
  "arguments": {
    "operations": [
      {
        "statement": "INSERT INTO orders (customer_id, order_date, status) VALUES ($1, NOW(), 'pending') RETURNING order_id",
        "params": [101]
      },
      {
        "statement": "INSERT INTO order_items (order_id, product_sku, quantity, price) VALUES ($1, $2, $3, $4)",
        "params": [9999, "GADGET-X", 2, 49.99]
      },
      {
        "statement": "UPDATE inventory SET stock_count = stock_count - $1 WHERE product_sku = $2 AND stock_count >= $1",
        "params": [2, "GADGET-X"]
      }
    ],
    "dbAlias": "main"
  }
}

성공 응답 콘텐츠 예시(JSON 문자열):

"{\"success\":true,\"results\":[{\"operation\":0,\"rowsAffected\":1},{\"operation\":1,\"rowsAffected\":1},{\"operation\":2,\"rowsAffected\":1}]}"

오류 응답 내용 예(JSON 문자열):

"{\"success\":false,\"error\":\"Error executing operation 2: new row for relation \\\"inventory\\\" violates check constraint \\\"stock_count_non_negative\\\"\",\"failedOperationIndex\":2}"

서버 및 세션 이벤트

클라이언트 연결을 로깅하려면 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 서버
다중 데이터베이스 연결 지원
쿼리, 실행, 스키마 검사 및 트랜잭션을 위한 도구
스키마 내성을 위한 리소스
포괄적인 문서 및 예제

Integrations

FastPostgresMCP 🐘⚡️ (모든 기능을 갖춘 다중 DB MCP 서버)

목적: AI 에이전트를 위한 MCP 서버

문제 해결 및 개발

테스트를 위한 CLI 사용

내장된 MCP 검사기로 테스트

일반적인 문제

✨ 핵심 기능

포함 사항(fastmcp 기능 활용)

📋 필수 조건

⚙️ 설치

옵션 1: NPM 패키지

옵션 2: 저장소 복제

🔑 구성(다중 데이터베이스 및 선택적 인증)

🚀 서버 실행(프로세스로)

옵션 1: 글로벌하게 설치된 패키지 사용

옵션 2: 프로젝트에서 패키지 사용

옵션 3: 복제된 저장소에서

fastmcp CLI 도구로 테스트

💻 프로그래밍 API 사용(라이브러리로)

기본 사용법

직접 함수 가져오기

구성 옵션

🔌 AI 클라이언트(Cursor, Claude Desktop)와 연결

커서 AI - 자세한 예

클로드 데스크탑

🛠️ MCP 기능 공개

인증(선택 사항)

자원

1. 데이터베이스 테이블 나열

2. 테이블 스키마 검사

도구

1. query_tool

2. execute_tool

3. schema_tool

4. transaction_tool

서버 및 세션 이벤트

🔒 보안 고려 사항

📜 라이센스

📋 변경 사항

1.0.0

`fastmcp` CLI 도구로 테스트

1. `query_tool`

2. `execute_tool`

3. `schema_tool`

4. `transaction_tool`