hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

Enables querying Parquet files through DuckDB, providing data analysis capabilities on structured files
Allows reading and querying Parquet files stored in Google Cloud Storage buckets
Provides tools for executing SQL queries against PostgreSQL databases, including SELECT, CREATE/INSERT, UPDATE, and DELETE operations

MCP 데이터베이스 서버

mcp-framework 로 구축된 MCP(Model Context Protocol) 서버는 데이터베이스(DuckDB를 통한 PostgreSQL) 및 Google Cloud Storage(GCS)와 상호작용하기 위한 도구와 리소스를 제공합니다.

필수 조건

Node.js 22 이상
타입스크립트
PostgreSQL(데이터베이스 기능에 필요)
Google Cloud 자격 증명(선택 사항, GCS 기능용)
Devbox ( make 명령을 사용한 로컬 개발용)

프로젝트 구조

지엑스피1

설치

저장소를 복제합니다.
git clone <repository-url> cd mcp-db
종속성 설치(일관성을 위해 Devbox 사용이 권장됨):
devbox install # Or using npm directly if not using Devbox # npm install
.env.example``.env 로 복사하고 환경 변수를 입력합니다.
cp .env.example .env # Edit .env with your details
프로젝트를 빌드하세요:
# Using make (requires Devbox) make build # Or using npm directly # npm run build

구성

환경 변수

다음 환경 변수(또는 명령줄 인수)를 사용하여 서버를 구성합니다.

DATABASE_URL : PostgreSQL 연결 문자열(supergateway로 실행하지 않는 한 필수).
DATABASE_URLS : 여러 데이터베이스 연결에 대한 alias=url 쌍의 쉼표로 구분된 목록( DATABASE_URL 의 대안).
LOG_LEVEL : 로깅 수준( debug , info , error ). 기본값: info .
GCS_BUCKET : 기본 Google Cloud Storage 버킷 이름(선택 사항).
GCP_SERVICE_ACCOUNT : Base64로 인코딩된 Google Cloud 서비스 계정 키 JSON(선택 사항, GCS 인증용).
GCS_KEY_ID / GCS_SECRET : DuckDB의 httpfs 확장을 위한 대체 GCS 자격 증명(선택 사항).
TRANSPORT : 전송 유형( stdio 또는 sse ). 기본값: stdio .
PORT : SSE 전송을 위한 포트 번호. 기본값: 3001 .
HOST : SSE 전송 호스트 이름입니다. 기본값: localhost .
API_KEY : 서버를 보호하기 위한 선택적 API 키(설정된 경우 클라이언트가 Authorization: Bearer <key> 헤더에서 제공해야 함).

명령줄 인수(예: --port 8080 , --gcs-bucket my-bucket )는 환경 변수보다 우선합니다. 자세한 내용은 src/config.ts 참조하세요.

데이터베이스 마이그레이션

이 프로젝트는 PostgreSQL 스키마 변경 관리를 위해 node-pg-migrate 사용합니다. 마이그레이션 실행 및 생성에 대한 자세한 내용은 위 README 원본의 "데이터베이스 마이그레이션" 섹션을 참조하세요.

참고: 이전에 언급한 npm run setup:db 명령은 현재 설정에 따라 검토 또는 업데이트가 필요할 수 있습니다.

서버 실행

편리한 개발 명령을 위해 Makefile 사용하세요(Devbox 필요):

# Run in development mode (builds and starts with nodemon for auto-restarts)
# Uses SSE transport by default on port 3001
make dev

# Run tests (if configured)
# make test

# Build for production
# make build

make 없이 실행하려면( npm run build 후):

# Run with stdio transport
node dist/index.js --transport stdio

# Run with SSE transport on default port 3001
node dist/index.js --transport sse

# Run with SSE on a different port
node dist/index.js --transport sse --port 8080

클라이언트 구성

MCP 클라이언트(예: mcp-cli , Claude Desktop)를 로컬 서버에 연결하려면:

SSE 전송의 경우(예: 포트 3001):

{
  "mcpServers": {
    "mcp-db-local": {
      "command": "node",
      "args": [
        "/path/to/mcp-db/dist/index.js", // Adjust path if needed
        "--transport", "sse",
        "--port", "3001" // Match the port the server is running on
      ],
      // Add "env" if API_KEY is set
      // "env": { "API_KEY": "your-secret-key" }
    }
  }
}

(참고: 이전 README의 Docker/supergateway 예제는 오래되었거나 다른 배포 설정에만 해당될 수 있습니다.)

Stdio Transport의 경우:

{
  "mcpServers": {
    "mcp-db-local": {
      "command": "node",
      "args": [
        "/path/to/mcp-db/dist/index.js", // Adjust path if needed
        "--transport", "stdio"
      ],
      // Add "env" if API_KEY is set
      // "env": { "API_KEY": "your-secret-key" }
    }
  }
}

GitHub에서 npx로 실행

npx를 사용하여 서버를 직접 실행할 수 있습니다(패키지의 빌드 단계 필요):

# Ensure required env vars are set
export DATABASE_URL="postgresql://user:password@localhost:5432/db"
export GCS_BUCKET="my-bucket"

npx github:dwarvesf/mcp-db --transport sse --port 3001

사용 가능한 도구

duckdb_insert : DuckDB를 통해 연결된 PostgreSQL 데이터베이스에 INSERT 문을 실행합니다. INSERT 쿼리만 허용됩니다.
duckdb_query : DuckDB의 postgres_query 함수를 사용하여 연결된 PostgreSQL 데이터베이스( postgres_db )에 직접 읽기 전용 SQL 쿼리를 실행합니다. 정규화되지 않은 테이블 이름에 자동으로 접두사를 붙입니다(예: my_table``postgres_db.public.my_table 이 됩니다).
duckdb_read_parquet : DuckDB를 사용하여 Parquet 파일을 쿼리합니다(구성된 경우 GCS에서).
gcs_directory_tree : 페이지 분할을 지원하는 GCS 버킷에서 디렉토리 트리 구조를 가져옵니다.

사용 가능한 리소스

mcp://gcs/objects ( gcs_objects ): 구성된 GCS 버킷에 있는 객체를 나열합니다.
mcp://db/tables ( sql_tables ): 구성된 PostgreSQL 데이터베이스에 있는 모든 테이블과 해당 열을 나열합니다.

개발: 새로운 도구/리소스 통합

이 프로젝트에서는 mcp-framework 사용합니다. 새 도구나 리소스를 추가하려면 다음을 수행하세요.

클래스 만들기:
- src/tools/ 또는 src/resources/ 에 새로운 .ts 파일을 만듭니다.
- MCPTool 또는 MCPResource 확장하는 클래스를 정의합니다.
- 필요한 속성(도구의 경우 name , description , schema )과 메서드(도구의 경우 execute , 리소스의 경우 read )를 구현합니다.
- 입력 검증(도구)을 위해 schema 속성에서 Zod를 사용합니다.
- 클래스 내에서(종종 생성자 내에서) 모든 종속성(DB 연결이나 GCS 클라이언트)을 초기화하는데, src/services/ 의 서비스나 src/config.ts 의 구성을 사용할 가능성이 있습니다.
예제 도구( src/tools/my_tool.ts ):
import { MCPTool } from "mcp-framework"; import { z } from "zod"; import { formatSuccessResponse } from "../utils.js"; import { getDuckDBConnection } from "../services/duckdb.js"; // Example dependency const MyToolInputSchema = z.object({ param1: z.string().describe("Description for parameter 1"), }); type MyToolInput = z.infer<typeof MyToolInputSchema>; export class MyTool extends MCPTool<MyToolInput> { name = "my_tool"; description = "Description of what my tool does."; schema = { // Matches Zod schema structure param1: { type: z.string(), description: "Description for parameter 1" }, }; async execute(args: MyToolInput): Promise<any> { console.error(`Handling tool request: ${this.name}`); const duckDBConn = getDuckDBConnection(); // Get dependency // ... implement logic using args and duckDBConn ... const result = { message: `Processed ${args.param1}` }; return formatSuccessResponse(result); } } export default MyTool; // Ensure default export
자동 검색:
- mcp-framework``src/tools 및 src/resources 디렉토리에 있는 파일에서 기본적으로 내보내진 도구/리소스 클래스를 자동으로 검색하여 등록합니다.
- 새 클래스가 해당 파일에서 default export 설정되어 있는지 확인하세요.
시험:
- 서버를 실행합니다( make dev ).
- 시작 로그를 확인하여 새 도구/리소스가 나열되어 있는지 확인하세요.
- MCP 클라이언트( mcp-cli 또는 MCP Inspector 등)를 사용하여 도구를 호출하거나 리소스를 읽고 기능을 확인합니다.

모범 사례

도구용 Zod를 사용하여 명확한 입력 스키마를 정의합니다.
execute / read 내에서 오류를 우아하게 처리하고 formatErrorResponse (또는 오류 발생)를 사용하여 형식화된 오류 응답을 반환합니다.
필요한 경우 getConfig() 를 통해 중앙화된 구성( src/config.ts )을 사용합니다.
데이터베이스 연결과 같은 종속성을 위해 src/services/ 에 있는 서비스 초기화 프로그램을 활용합니다.
가시성을 위해 로깅( console.error )을 추가합니다.

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

PostgreSQL, DuckDB, Google Cloud Storage Parquet 파일을 포함한 데이터베이스와 상호 작용하기 위한 도구를 제공하는 모델 컨텍스트 프로토콜 서버입니다.

MCP Database Server