PostgreSQL MCP 서버
PostgreSQL 데이터베이스 관리 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 기존 PostgreSQL 설정 분석, 구현 지침 제공, 데이터베이스 문제 디버깅, 스키마 관리, 데이터 마이그레이션 및 데이터베이스 성능 모니터링을 지원합니다.
버전 0.2.0
특징
서버는 다음과 같은 도구를 제공합니다.
1. 데이터베이스 분석 및 설정
1.1. 데이터베이스 분석( analyze_database )
PostgreSQL 데이터베이스 구성 및 성능 측정 항목을 분석합니다.
- 구성 분석
- 성과 지표
- 보안 평가
- 최적화를 위한 권장 사항
지엑스피1
1.2. 설정 지침 받기( get_setup_instructions )
단계별 PostgreSQL 설치 및 구성 지침을 제공합니다.
- 플랫폼별 설치 단계
- 구성 권장 사항
- 보안 모범 사례
- 설치 후 작업
// Example usage
{
"platform": "linux", // Required: "linux" | "macos" | "windows"
"version": "15", // Optional: PostgreSQL version
"useCase": "production" // Optional: "development" | "production"
}
1.3. 디버그 데이터베이스( debug_database )
일반적인 PostgreSQL 문제를 디버깅합니다.
// Example usage
{
"issue": "performance", // Required: "connection" | "performance" | "locks" | "replication"
"logLevel": "debug" // Optional: "info" | "debug" | "trace"
}
2. 스키마 관리
2.1. 스키마 정보 가져오기( get_schema_info )
데이터베이스 또는 특정 테이블에 대한 자세한 스키마 정보를 얻으세요.
- 데이터베이스의 테이블 목록
- 열 정의
- 제약 조건(기본 키, 외래 키 등)
- 인덱스
// Example usage
{
"tableName": "users" // Optional: specific table to get info for
}
2.2. 테이블 생성( create_table )
지정된 열로 새 테이블을 만듭니다.
- 열 이름과 유형 정의
- null 허용 제약 조건 설정
- 기본값 설정
// Example usage
{
"tableName": "users", // Required
"columns": [ // Required
{ "name": "id", "type": "SERIAL", "nullable": false },
{ "name": "username", "type": "VARCHAR(100)", "nullable": false },
{ "name": "email", "type": "VARCHAR(255)", "nullable": false },
{ "name": "created_at", "type": "TIMESTAMP", "default": "NOW()" }
]
}
2.3. 테이블 변경( alter_table )
기존 테이블 수정:
- 새로운 열 추가
- 열 유형 또는 제약 조건 수정
- 열 삭제
// Example usage
{
"tableName": "users", // Required
"operations": [ // Required
{ "type": "add", "columnName": "last_login", "dataType": "TIMESTAMP" },
{ "type": "alter", "columnName": "email", "nullable": false },
{ "type": "drop", "columnName": "temporary_field" }
]
}
2.4. 열거형 가져오기( get_enums )
PostgreSQL ENUM 유형에 대한 정보를 얻으세요.
// Example usage
{
"schema": "public", // Optional
"enumName": "user_status" // Optional
}
2.5. 열거형 생성( create_enum )
데이터베이스에 새로운 ENUM 유형을 만듭니다.
// Example usage
{
"enumName": "order_status", // Required
"values": ["pending", "processing", "shipped", "delivered"], // Required
"schema": "public", // Optional
"ifNotExists": true // Optional
}
3. 데이터 마이그레이션
3.1. 테이블 데이터 내보내기( export_table_data )
JSON 또는 CSV 형식으로 테이블 데이터 내보내기:
- WHERE 절을 사용하여 데이터 필터링
- 행 수 제한
- 출력 형식을 선택하세요
// Example usage
{
"tableName": "users", // Required
"outputPath": "./exports/users.json", // Required
"where": "created_at > '2023-01-01'", // Optional
"limit": 1000, // Optional
"format": "json" // Optional: "json" | "csv"
}
3.2. 테이블 데이터 가져오기( import_table_data )
JSON 또는 CSV 파일에서 데이터 가져오기:
- 선택적으로 가져오기 전에 테이블을 잘라냅니다.
- 다양한 형식 지원
- 사용자 정의 CSV 구분 기호
// Example usage
{
"tableName": "users", // Required
"inputPath": "./imports/users.json", // Required
"truncateFirst": false, // Optional
"format": "json", // Optional: "json" | "csv"
"delimiter": "," // Optional: for CSV files
}
3.3. 데이터베이스 간 복사( copy_between_databases )
두 PostgreSQL 데이터베이스 간에 데이터 복사:
- WHERE 절을 사용하여 데이터 필터링
- 선택적으로 대상 테이블을 잘라냅니다.
// Example usage
{
"sourceConnectionString": "postgresql://user:password@localhost:5432/source_db", // Required
"targetConnectionString": "postgresql://user:password@localhost:5432/target_db", // Required
"tableName": "users", // Required
"where": "active = true", // Optional
"truncateTarget": false // Optional
}
4. 모니터링
4.1. 모니터 데이터베이스( monitor_database )
PostgreSQL 데이터베이스의 실시간 모니터링:
- 데이터베이스 메트릭(연결, 캐시 적중률 등)
- 테이블 메트릭(크기, 행 수, 데드 튜플)
- 활성 쿼리 정보
- 잠금 정보
- 복제 상태
- 구성 가능한 알림
// Example usage
{
"includeTables": true, // Optional
"includeQueries": true, // Optional
"includeLocks": true, // Optional
"includeReplication": false, // Optional
"alertThresholds": { // Optional
"connectionPercentage": 80,
"longRunningQuerySeconds": 30,
"cacheHitRatio": 0.95,
"deadTuplesPercentage": 10,
"vacuumAge": 7
}
}
5. 기능
5.1. 함수 가져오기( get_functions )
PostgreSQL 함수에 대한 정보를 얻으세요.
// Example usage
{
"functionName": "calculate_total", // Optional
"schema": "public" // Optional
}
5.2. 함수 생성( create_function )
PostgreSQL 함수를 생성하거나 교체합니다.
// Example usage
{
"functionName": "get_user_count", // Required
"parameters": "", // Required (empty if no params)
"returnType": "integer", // Required
"functionBody": "SELECT count(*) FROM users;", // Required
"language": "sql", // Optional
"volatility": "STABLE", // Optional
"schema": "public", // Optional
"security": "INVOKER", // Optional
"replace": true // Optional
}
5.3. Drop 함수( drop_function )
PostgreSQL 함수를 삭제합니다.
// Example usage
{
"functionName": "old_function", // Required
"parameters": "integer", // Optional: required for overloaded functions
"schema": "public", // Optional
"ifExists": true, // Optional
"cascade": false // Optional
}
6. 행 수준 보안(RLS)
6.1. RLS 활성화( enable_rls )
테이블에 행 수준 보안을 활성화합니다.
// Example usage
{
"tableName": "sensitive_data", // Required
"schema": "secure" // Optional
}
6.2. RLS 비활성화( disable_rls )
테이블에서 행 수준 보안을 비활성화합니다.
// Example usage
{
"tableName": "sensitive_data", // Required
"schema": "secure" // Optional
}
6.3. RLS 정책 생성( create_rls_policy )
행 수준 보안 정책을 만듭니다.
// Example usage
{
"tableName": "documents", // Required
"policyName": "user_can_see_own_docs", // Required
"using": "owner_id = current_user_id()", // Required
"check": "owner_id = current_user_id()", // Optional
"schema": "public", // Optional
"command": "SELECT", // Optional
"role": "app_user", // Optional
"replace": false // Optional
}
6.4. RLS 정책 편집( edit_rls_policy )
기존 행 수준 보안 정책을 편집합니다.
// Example usage
{
"tableName": "documents", // Required
"policyName": "user_can_see_own_docs", // Required
"schema": "public", // Optional
"roles": ["app_user", "admin_user"], // Optional: New roles (empty or omit to keep existing/use default)
"using": "owner_id = current_user_id() OR is_admin(current_user_id())", // Optional: New USING expression
"check": "owner_id = current_user_id()" // Optional: New WITH CHECK expression
}
6.5. RLS 정책 삭제( drop_rls_policy )
행 수준 보안 정책을 삭제합니다.
// Example usage
{
"tableName": "documents", // Required
"policyName": "old_policy", // Required
"schema": "public", // Optional
"ifExists": true // Optional
}
6.6. RLS 정책 가져오기( get_rls_policies )
행 수준 보안 정책을 가져옵니다.
// Example usage
{
"tableName": "documents", // Optional
"schema": "public" // Optional
}
7. 트리거
7.1. 트리거 가져오기( get_triggers )
PostgreSQL 트리거에 대한 정보를 얻으세요.
// Example usage
{
"tableName": "audit_log", // Optional
"schema": "public" // Optional
}
7.2. 트리거 생성( create_trigger )
PostgreSQL 트리거를 생성합니다.
// Example usage
{
"triggerName": "log_user_update", // Required
"tableName": "users", // Required
"functionName": "audit_user_change", // Required
"schema": "public", // Optional
"timing": "AFTER", // Optional
"events": ["UPDATE"], // Optional
"when": "OLD.email IS DISTINCT FROM NEW.email", // Optional
"forEach": "ROW", // Optional
"replace": false // Optional
}
7.3. 드롭 트리거( drop_trigger )
PostgreSQL 트리거를 삭제합니다.
// Example usage
{
"triggerName": "old_trigger", // Required
"tableName": "users", // Required
"schema": "public", // Optional
"ifExists": true, // Optional
"cascade": false // Optional
}
7.4. 트리거 상태 설정( set_trigger_state )
PostgreSQL 트리거를 활성화하거나 비활성화합니다.
// Example usage
{
"triggerName": "log_user_update", // Required
"tableName": "users", // Required
"enable": false, // Required: true to enable, false to disable
"schema": "public" // Optional
}
필수 조건
- 노드.js >= 18.0.0
- PostgreSQL 서버(대상 데이터베이스 작업용)
- 대상 PostgreSQL 인스턴스에 대한 네트워크 액세스
설치
Smithery를 통해 설치
Smithery를 통해 Claude Desktop에 postgresql-mcp-server를 자동으로 설치하려면:
npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude
수동 설치
- 저장소를 복제합니다
- 종속성 설치:
- 서버를 빌드하세요:
- MCP 설정 파일에 추가합니다(예: IDE 설정이나 글로벌 MCP 구성):서버의 연결 문자열을 구성하는 방법에는 여러 가지가 있으며, 우선순위는 다음과 같습니다.
- 도구별 인수 : 특정 도구를 호출할 때
connectionString 인수에 직접 제공되는 경우 해당 값이 해당 호출에 사용됩니다. - CLI 인수 :
-cs 또는 --connection-string 인수를 사용하여 서버를 시작할 때 기본 연결 문자열을 제공할 수 있습니다. - 환경 변수 : 위의 두 가지 모두 제공되지 않으면 서버는
POSTGRES_CONNECTION_STRING 환경 변수를 찾습니다.
이러한 방법을 통해 연결 문자열을 찾을 수 없으면 데이터베이스 연결이 필요한 도구가 실패합니다.
MCP 설정에서 CLI 인수를 사용하는 예:
{
"mcpServers": {
"postgresql-mcp": {
"command": "node",
"args": [
"/path/to/postgresql-mcp-server/build/index.js",
"--connection-string",
"postgresql://username:password@server:port/dbname"
// Optionally, add "--tools-config", "/path/to/your/mcp-tools.json"
],
"disabled": false,
"alwaysAllow": []
// Note: 'env' block for POSTGRES_CONNECTION_STRING can still be used as a fallback
// if --connection-string is not provided in args.
}
}
}
환경 변수를 사용하는 예(CLI 인수를 사용하지 않는 경우):
{
"mcpServers": {
"postgresql-mcp": {
"command": "node",
"args": [
"/path/to/postgresql-mcp-server/build/index.js"
// Optionally, add "--tools-config", "/path/to/your/mcp-tools.json"
],
"disabled": false,
"alwaysAllow": [],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://username:password@server:port/dbname"
}
}
}
}
--connection-string CLI 인수나 POSTGRES_CONNECTION_STRING 환경 변수를 사용하면 대부분의 도구 호출에서 connectionString 인수가 선택 사항이 됩니다.
도구 구성
서버는 외부 JSON 구성 파일을 통해 어떤 도구가 활성화되는지 필터링하는 기능을 지원합니다.
- CLI 옵션 :
-tc <path> 또는 --tools-config <path> 사용하여 도구 구성 파일의 경로를 지정합니다. - 파일 형식 : JSON 파일에는 도구 이름 문자열 배열을 보관하는
enabledTools 키가 있는 개체가 있어야 합니다.예시 mcp-tools.json :{
"enabledTools": [
"get_schema_info",
"analyze_database",
"export_table_data"
]
}
- 행동 :
- 구성 파일이 제공되고 유효한 경우, 나열된 도구만 활성화됩니다.
- 파일이 제공되지 않거나, 유효하지 않거나, 읽을 수 없는 경우 모든 도구가 기본적으로 활성화됩니다.
- 서버는 이 구성에 따라 어떤 도구가 활성화되었는지 기록합니다.
개발
npm run dev - 핫 리로드로 개발 서버 시작npm run lint - ESLint 실행npm test - 테스트 실행(구성된 경우)
보안 고려 사항
- 연결 보안
- 서버는 다음 우선순위에 따라 데이터베이스 연결 문자열을 결정합니다.
- 도구의 인수에 직접 제공되는
connectionString . --connection-string 서버를 시작할 때 사용되는 CLI 인수입니다.POSTGRES_CONNECTION_STRING 환경 변수.
- 연결 문자열(특히 자격 증명이 있는 문자열)이 안전하게 관리되는지 확인하세요.
pg (이전에는 @vercel/postgres )를 통한 연결 풀링을 사용합니다.- 연결 문자열을 검증합니다.
- SSL/TLS 연결을 지원합니다(연결 문자열을 통해 구성).
- 쿼리 안전
- 미리 정의된 작업을 실행합니다. 가능한 경우 임의의 SQL 실행을 방지합니다.
- 해당되는 경우 매개변수화된 쿼리를 사용하여 SQL 주입을 방지합니다.
- 감사를 위한 로그 작업입니다.
- 입증
- 연결 문자열을 통한 PostgreSQL의 인증 메커니즘을 사용합니다.
- 데이터베이스 자격 증명을 안전하게 관리하세요. 가능하다면 클라이언트 요청에 직접 코딩하지 마세요. 서버를 구성할 때는
--connection-string CLI 옵션이나 POSTGRES_CONNECTION_STRING 환경 변수를 사용하는 것이 좋습니다.
모범 사례
--connection-string CLI 옵션이나 POSTGRES_CONNECTION_STRING 환경 변수를 사용하여 기본 데이터베이스 연결 문자열을 안전하게 구성합니다.- 도구가 기본 데이터베이스가 아닌 다른 데이터베이스에 연결해야 하는 경우 해당 도구의 인수에
connectionString 직접 제공하세요. - 항상 적절한 자격 증명을 포함한 보안 연결 문자열을 사용하고, 이는
POSTGRES_CONNECTION_STRING 환경 변수를 통해 구성하는 것이 좋습니다. - 민감한 환경에는 프로덕션 보안 권장 사항을 따르세요.
monitor_database 도구를 사용하여 데이터베이스 성능을 정기적으로 모니터링하고 분석합니다.- PostgreSQL 버전을 최신 상태로 유지하세요.
- 적절한 백업 전략을 독립적으로 구현합니다.
- 더 나은 리소스 관리를 위해 연결 풀링을 사용합니다(내부적으로 처리).
- 적절한 오류 처리 및 로깅을 구현합니다.
- 정기적인 보안 감사 및 업데이트.
오류 처리
서버는 다음에 대한 오류 처리를 구현합니다.
오류는 표준 MCP 오류 형식으로 반환됩니다.
기여하다
- 저장소를 포크하세요
- 기능 브랜치 생성
- 변경 사항을 커밋하세요
- 지점으로 밀어 넣기
- 풀 리퀘스트 만들기
특허
이 프로젝트는 AGPLv3 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.