Multi Database MCP Server

by FreePeak
Verified
MIT License
97
  • Linux
  • Apple

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.

Integrations

  • Includes support link integration for the project via Buy Me A Coffee, allowing users to financially support the development of the MCP server.

  • Planned for Q4 2025 to provide search-optimized AI interactions with Elasticsearch, enabling context-aware queries and operations.

  • Listed in the roadmap for Q3 2025 to add support for document-oriented schema understanding, enabling AI reasoning with MongoDB databases.

다중 데이터베이스 MCP 서버

DB MCP 서버란 무엇인가요?

DB MCP 서버는 AI 모델이 여러 데이터베이스와 동시에 상호 작용할 수 있는 표준화된 방식을 제공합니다. FreePeak/cortex 프레임워크 기반으로 구축된 이 서버를 통해 AI 어시스턴트는 통합 인터페이스를 통해 SQL 쿼리 실행, 트랜잭션 관리, 스키마 탐색, 그리고 다양한 데이터베이스 시스템 성능 분석을 수행할 수 있습니다.

핵심 개념

다중 데이터베이스 지원

기존 데이터베이스 커넥터와 달리 DB MCP 서버는 여러 데이터베이스에 동시에 연결하고 상호 작용할 수 있습니다.

지엑스피1

동적 도구 생성

연결된 각 데이터베이스에 대해 서버는 자동으로 일련의 특수 도구를 생성합니다.

// For a database with ID "mysql1", these tools are generated: query_mysql1 // Execute SQL queries execute_mysql1 // Run data modification statements transaction_mysql1 // Manage transactions schema_mysql1 // Explore database schema performance_mysql1 // Analyze query performance

클린 아키텍처

서버는 다음 계층에 대해 클린 아키텍처 원칙을 따릅니다.

  1. 도메인 계층 : 핵심 비즈니스 엔터티 및 인터페이스
  2. 저장소 계층 : 데이터 액세스 구현
  3. 사용 사례 계층 : 애플리케이션 비즈니스 로직
  4. 전달 계층 : 외부 인터페이스(MCP 도구)

특징

  • 동시 다중 데이터베이스 지원 : 여러 MySQL 및 PostgreSQL 데이터베이스에 동시에 연결하고 상호 작용합니다.
  • 데이터베이스별 도구 생성 : 연결된 각 데이터베이스에 대한 특수 도구를 자동으로 생성합니다.
  • 클린 아키텍처 : 관심사를 명확하게 분리한 모듈식 디자인
  • OpenAI Agents SDK 호환성 : AI 어시스턴트와의 원활한 통합을 위해 OpenAI Agents SDK와 완벽하게 호환됩니다.
  • 동적 데이터베이스 도구 :
    • 매개변수를 사용하여 SQL 쿼리 실행
    • 적절한 오류 처리를 통해 데이터 수정 문을 실행합니다.
    • 세션 간 데이터베이스 트랜잭션 관리
    • 데이터베이스 스키마와 관계 탐색
    • 쿼리 성능을 분석하고 최적화 제안을 받습니다.
  • 통합 인터페이스 : 다양한 데이터베이스 유형에서 일관된 상호 작용 패턴
  • 연결 관리 : 여러 데이터베이스 연결을 위한 간단한 구성

현재 지원되는 데이터베이스

데이터 베이스상태특징
MySQL✅ 전체 지원쿼리, 트랜잭션, 스키마 분석, 성능 통찰력
포스트그레스큐엘✅ 전체 지원(v9.6-17)쿼리, 트랜잭션, 스키마 분석, 성능 통찰력

빠른 시작

Docker 사용

가장 빠르게 시작하는 방법은 Docker를 사용하는 것입니다.

# Pull the latest image docker pull freepeak/db-mcp-server:latest # Option 1: Run with environment variables (recommended) docker run -p 9092:9092 \ -v $(pwd)/config.json:/app/my-config.json \ -e TRANSPORT_MODE=sse \ -e CONFIG_PATH=/app/my-config.json \ freepeak/db-mcp-server # Option 2: Override the entrypoint docker run -p 9092:9092 \ -v $(pwd)/config.json:/app/my-config.json \ --entrypoint /app/server \ freepeak/db-mcp-server \ -t sse -c /app/my-config.json # Option 3: Use shell to execute the command docker run -p 9092:9092 \ -v $(pwd)/config.json:/app/my-config.json \ freepeak/db-mcp-server \ /bin/sh -c "/app/server -t sse -c /app/my-config.json"

참고 : 컨테이너에 이미 /app/my-config.json 파일이 있으므로 /app/config.json 에 마운트합니다. 플랫폼 불일치 경고가 발생하면 --platform linux/amd64 또는 --platform linux/arm64 옵션을 사용하여 플랫폼을 지정할 수 있습니다.

출처에서

# Clone the repository git clone https://github.com/FreePeak/db-mcp-server.git cd db-mcp-server # Build the server make build # Run the server in SSE mode ./server -t sse -c config.json

서버 실행

서버는 다양한 사용 사례에 맞게 여러 전송 모드를 지원합니다.

STDIO 모드(IDE 통합용)

AI 코딩 어시스턴트와의 통합에 이상적:

# Run the server in STDIO mode ./server -t stdio -c config.json

출력은 JSON-RPC 메시지로 stdout으로 전송되고, 로그는 stderr로 전송됩니다.

커서 통합을 위해 .cursor/mcp.json 에 다음을 추가하세요.

{ "mcpServers": { "stdio-db-mcp-server": { "command": "/path/to/db-mcp-server/server", "args": [ "-t", "stdio", "-c", "/path/to/config.json" ] } } }

SSE 모드(서버에서 보낸 이벤트)

웹 기반 애플리케이션 및 서비스의 경우:

# Run with default host (localhost) and port (9092) ./server -t sse -c config.json # Specify a custom host and port ./server -t sse -host 0.0.0.0 -port 8080 -c config.json

이벤트 스트림을 위해 클라이언트를 http://localhost:9092/sse 에 연결합니다.

도커 컴포즈

데이터베이스 컨테이너가 있는 개발 환경의 경우 완전한 docker-compose.yml 파일을 제공합니다.

services: db-mcp-server: image: freepeak/db-mcp-server:latest ports: - "9092:9092" volumes: - ./config.json:/app/config.json - ./wait-for-it.sh:/app/wait-for-it.sh command: [ "/bin/sh", "-c", "chmod +x /app/wait-for-it.sh && /app/wait-for-it.sh mysql1:3306 -t 60 && /app/wait-for-it.sh mysql2:3306 -t 60 && /app/wait-for-it.sh postgres1:5432 -t 60 && /app/wait-for-it.sh postgres3:5432 -t 60 && /app/server -t sse -c /app/config.json", ] depends_on: mysql1: condition: service_healthy mysql2: condition: service_healthy postgres1: condition: service_healthy postgres3: condition: service_healthy mysql1: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: password MYSQL_DATABASE: db1 MYSQL_USER: user1 MYSQL_PASSWORD: password1 MYSQL_AUTHENTICATION_PLUGIN: mysql_native_password ports: - "13306:3306" volumes: - mysql1_data:/var/lib/mysql command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci healthcheck: test: [ "CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-ppassword", ] interval: 5s timeout: 5s retries: 10 mysql2: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: password MYSQL_DATABASE: db2 MYSQL_USER: user2 MYSQL_PASSWORD: password2 MYSQL_AUTHENTICATION_PLUGIN: mysql_native_password ports: - "13307:3306" volumes: - mysql2_data:/var/lib/mysql command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci healthcheck: test: [ "CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-ppassword", ] interval: 5s timeout: 5s retries: 10 postgres1: image: postgres:15 environment: POSTGRES_USER: user1 POSTGRES_PASSWORD: password1 POSTGRES_DB: db1 ports: - "15432:5432" volumes: - postgres1_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U user1 -d db1"] interval: 5s timeout: 5s retries: 10 postgres2: image: postgres:17 environment: POSTGRES_USER: user2 POSTGRES_PASSWORD: password2 POSTGRES_DB: db2 ports: - "15433:5432" volumes: - postgres2_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U user2 -d db2"] interval: 5s timeout: 5s retries: 10 postgres3: image: postgres:16.3-alpine environment: POSTGRES_USER: screener POSTGRES_PASSWORD: screenerpass POSTGRES_DB: screenerdb ports: - "15434:5432" volumes: - postgres_screener_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U screener -d screenerdb"] interval: 5s timeout: 5s retries: 10 volumes: mysql1_data: mysql2_data: postgres1_data: postgres2_data: postgres_screener_data:

이 docker-compose 설정의 주요 기능:

  • db-mcp-server 컨테이너는 시작하기 전에 모든 데이터베이스 서비스가 준비될 때까지 기다립니다.
  • 여러 데이터베이스 유형과 버전이 포함되어 있습니다(MySQL 8.0, PostgreSQL 15, 16.3 및 17)
  • 모든 데이터베이스에는 서버가 연결되기 전에 데이터베이스가 완전히 초기화되었는지 확인하기 위한 상태 검사가 포함되어 있습니다.
  • 모든 데이터베이스 서비스에 대한 영구 볼륨
  • 필요한 경우 직접 데이터베이스에 액세스할 수 있는 노출된 포트

설정은 wait-for-it.sh 스크립트를 사용하여 서버를 시작하기 전에 모든 데이터베이스 서비스가 완전히 준비되었는지 확인합니다. 이 스크립트는 진행하기 전에 TCP 호스트/포트를 사용할 수 있는지 확인합니다. 이 스크립트를 프로젝트 디렉터리에 포함해야 합니다. Docker 설정은 이 스크립트를 컨테이너에 마운트하고 데이터베이스 가용성을 확인하는 데 사용합니다.

이 설정을 사용하려면:

# Start all services docker-compose up -d # Check logs docker-compose logs -f db-mcp-server # Stop all services docker-compose down

docker-compose.yml에 정의된 서비스와 일치하는 연결 세부 정보가 config.json 파일에 포함되어 있는지 확인하세요.

구성

데이터베이스 구성

데이터베이스 연결을 포함하는 config.json 파일을 만듭니다.

{ "connections": [ { "id": "mysql1", "type": "mysql", "host": "mysql1", "port": 3306, "name": "db1", "user": "user1", "password": "password1" }, { "id": "mysql2", "type": "mysql", "host": "mysql2", "port": 3306, "name": "db2", "user": "user2", "password": "password2" }, { "id": "postgres1", "type": "postgres", "host": "postgres1", "port": 5432, "name": "db1", "user": "user1", "password": "password1" }, { "id": "postgres2", "type": "postgres", "host": "postgres2", "port": 5432, "name": "db2", "user": "user2", "password": "password2" }, { "id": "postgres3", "type": "postgres", "host": "postgres3", "port": 5432, "name": "screenerdb", "user": "screener", "password": "screenerpass" } ] }

docker-compose 설정을 사용할 때 host 값이 docker-compose.yml 파일에 있는 서비스 이름과 일치해야 합니다.

명령줄 옵션

서버는 다양한 명령줄 옵션을 지원합니다.

# Basic options ./server -t <transport> -c <config-file> # Available transports: stdio, sse # For SSE transport, additional options: ./server -t sse -host <hostname> -port <port> -c <config-file> # Direct database configuration: ./server -t stdio -db-config '{"connections":[...]}' # Environment variable configuration: export DB_CONFIG='{"connections":[...]}' ./server -t stdio

사용 가능한 도구

연결된 각 데이터베이스(예: "mysql1", "mysql2")에 대해 서버는 다음을 생성합니다.

도구 명명 규칙

서버는 다음 형식을 따르는 이름을 가진 도구를 자동으로 생성합니다.

<tool_type>_<database_id>

어디:

  • <tool_type> : 쿼리, 실행, 트랜잭션, 스키마, 성능 중 하나
  • <database_id> : 구성에 정의된 데이터베이스의 ID

ID가 "mysql1"인 데이터베이스에 대한 도구 이름 예:

  • query_mysql1
  • execute_mysql1
  • transaction_mysql1
  • schema_mysql1
  • performance_mysql1

데이터베이스별 도구

  • query_<dbid> : 지정된 데이터베이스에서 SQL 쿼리를 실행합니다.
    { "query": "SELECT * FROM users WHERE age > ?", "params": [30] }
  • execute_<dbid> : SQL 문(INSERT, UPDATE, DELETE)을 실행합니다.
    { "statement": "INSERT INTO users (name, email) VALUES (?, ?)", "params": ["John Doe", "john@example.com"] }
  • transaction_<dbid> : 데이터베이스 트랜잭션 관리
    // Begin transaction { "action": "begin", "readOnly": false } // Execute within transaction { "action": "execute", "transactionId": "<from begin response>", "statement": "UPDATE users SET active = ? WHERE id = ?", "params": [true, 42] } // Commit transaction { "action": "commit", "transactionId": "<from begin response>" }
  • schema_<dbid> : 데이터베이스 스키마 정보를 가져옵니다.
    { "random_string": "dummy" }
  • performance_<dbid> : 쿼리 성능 분석
    { "action": "analyzeQuery", "query": "SELECT * FROM users WHERE name LIKE ?" }

글로벌 도구

  • list_databases : 구성된 모든 데이터베이스 연결을 나열합니다.
    {}

예시

여러 데이터베이스 쿼리

// Query the first database { "name": "query_mysql1", "parameters": { "query": "SELECT * FROM users LIMIT 5" } } // Query the second database { "name": "query_mysql2", "parameters": { "query": "SELECT * FROM products LIMIT 5" } }

거래 실행

// Begin transaction { "name": "transaction_mysql1", "parameters": { "action": "begin" } } // Response contains transactionId // Execute within transaction { "name": "transaction_mysql1", "parameters": { "action": "execute", "transactionId": "tx_12345", "statement": "INSERT INTO orders (user_id, product_id) VALUES (?, ?)", "params": [1, 2] } } // Commit transaction { "name": "transaction_mysql1", "parameters": { "action": "commit", "transactionId": "tx_12345" } }

로드맵

우리는 광범위한 데이터베이스 시스템을 지원하기 위해 DB MCP 서버를 확장하는 데 전념하고 있습니다.

2025년 3분기

  • MongoDB - 문서 지향 데이터베이스 작업 지원
  • SQLite - 가벼운 임베디드 데이터베이스 통합
  • MariaDB - MySQL 구현과 완벽한 기능 동등성

2025년 4분기

  • Microsoft SQL Server - T-SQL 기능을 갖춘 엔터프라이즈 데이터베이스 지원
  • Oracle Database - 엔터프라이즈급 통합
  • Redis - 키-값 저장소 작업

2026

  • Cassandra - 분산형 NoSQL 데이터베이스 지원
  • Elasticsearch - 전문 검색 및 분석 기능
  • CockroachDB - 글로벌 규모 애플리케이션을 위한 분산 SQL 데이터베이스
  • DynamoDB - AWS 기반 NoSQL 데이터베이스 통합
  • Neo4j - 그래프 데이터베이스 지원
  • ClickHouse - 분석 데이터베이스 지원

문제 해결

일반적인 문제

  1. 연결 오류 : config.json 에서 데이터베이스 연결 설정을 확인하세요.
  2. 도구를 찾을 수 없음 : 서버가 실행 중인지 확인하고 도구 이름 접두사를 확인하세요.
  3. 실패한 쿼리 : SQL 구문 및 데이터베이스 권한을 확인하세요.
  4. Docker 볼륨 마운트 오류 : mountpoint for /app/config.json: not a directory 와 같은 오류가 표시되는 경우, 컨테이너가 해당 경로에 이미 파일을 가지고 있기 때문입니다. 다른 경로(예: /app/my-config.json )에 마운트하고 구성을 그에 맞게 업데이트하세요.
  5. Docker 명령 오류 : Docker에서 명령 관련 오류가 발생하면 다음 방법 중 하나를 사용하세요.
    • 환경 변수를 사용하세요: -e TRANSPORT_MODE=sse -e CONFIG_PATH=/app/my-config.json
    • 진입점을 재정의합니다: --entrypoint /app/server freepeak/db-mcp-server -t sse -c /app/my-config.json
    • 셸 실행을 사용하세요: freepeak/db-mcp-server /bin/sh -c "/app/server -t sse -c /app/my-config.json"
  6. Wait-for-it.sh가 없거나 작동하지 않음 : wait-for-it.sh와 관련된 오류가 표시되는 경우:
    • 프로젝트 디렉토리에 파일이 있는지 확인하세요.
    • 실행 권한이 있는지 확인하세요: chmod +x wait-for-it.sh
    • 적절한 줄 끝을 확인하세요(Windows 스타일 CRLF가 아닌 Unix 스타일 LF를 사용하세요)
    • 여전히 문제가 발생하는 경우 docker-compose.yml을 수정하여 서비스 상태 확인을 대신 사용할 수 있습니다.

로그

서버는 다음에 로그를 기록합니다.

  • STDIO 모드: stderr
  • SSE 모드: stdout 및 ./logs/db-mcp-server.log

-debug 플래그로 디버그 로깅을 활성화합니다.

./server -t sse -debug -c config.json

기여하다

참여를 환영합니다! 다음과 같은 방법으로 도움을 주세요.

  1. 저장소를 포크하세요
  2. 기능 브랜치를 만듭니다 : git checkout -b new-feature
  3. 변경 사항을 커밋하세요 : git commit -am 'Add new feature'
  4. 브랜치에 푸시 : git push origin new-feature
  5. 풀 리퀘스트 제출

귀하의 코드가 당사의 코딩 표준을 따르고 적절한 테스트를 포함하고 있는지 확인하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

지원 및 연락처

  • 질문이나 문제가 있으면 mnhatlinh.doan@gmail.com 으로 이메일을 보내주세요.
  • 이슈를 직접 열어보세요: 이슈 트래커
  • DB MCP Server가 귀하의 작업에 도움이 된다면 다음을 지원해 주시기 바랍니다.

커서 통합

도구 명명 규칙

MCP 서버는 Cursor가 예상하는 형식과 일치하는 이름으로 도구를 등록합니다. 도구 이름은 다음 형식을 따릅니다.

mcp_<servername>_<tooltype>_<dbID>

예: mcp_mysql1_db_mcp_server_stdio_schema_mysql1_db

서버는 기본적으로 mysql1_db_mcp_server_stdio 라는 이름을 사용하는데, 이는 mcp.json 파일의 커서 구성과 일치해야 합니다.

커서 구성

커서 구성( ~/.cursor/mcp.json )에서 다음과 같은 구성이 있어야 합니다.

{ "mcpServers": { "multidb": { "command": "/path/to/db-mcp-server/server", "args": [ "-t", "stdio", "-c", "/path/to/database_config.json" ] } } }

서버는 구성에 있는 데이터베이스 식별자와 일치하는 간단한 이름으로 도구를 자동으로 등록합니다.

커서에서 MCP 도구 사용

DB MCP 서버가 실행되고 Cursor에서 제대로 구성되면 AI 어시스턴트 대화에서 MCP 도구를 사용할 수 있습니다. 도구는 다음과 같은 명명 패턴을 따릅니다.

mcp_<server_name>_<tool_type>_<database_id>

어디:

  • <server_name> 은 .cursor/mcp.json에 정의된 이름입니다(예: "multidb").
  • <tool_type> 은 다음 중 하나입니다: 쿼리, 실행, 트랜잭션, 스키마, 성능, 목록_데이터베이스
  • <database_id> 는 구성의 데이터베이스 ID입니다(list_databases에는 필요하지 않음).

예:

데이터베이스 ID가 "mysql1"인 "multidb"라는 서버의 경우:

  1. 모든 데이터베이스 나열 :
mcp_multidb_list_databases
  1. 데이터베이스 쿼리 :
mcp_multidb_query_mysql1 Query: SELECT * FROM users LIMIT 10
  1. 데이터베이스 스키마 보기 :
mcp_multidb_schema_mysql1
  1. 실행 명령문 :
mcp_multidb_execute_mysql1 Statement: INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com')
  1. 거래 관리 :
mcp_multidb_transaction_mysql1 Action: begin

커서에서 MCP 도구 문제 해결

AI 어시스턴트가 MCP 도구를 호출할 수 없는 경우:

  1. 서버가 실행 중인지 확인하세요( ps aux | grep server 로 확인)
  2. .cursor/mcp.json 구성이 올바른지 확인하세요.
  3. .env의 server_name이 MCP 도구 호출에 있는 내용과 일치하는지 확인하세요.
  4. 구성 변경 후 커서를 다시 시작합니다.
  5. 오류가 있는지 로그/ 디렉토리의 로그를 확인하세요.

OpenAI 에이전트 SDK 통합

DB MCP 서버는 OpenAI의 Agents SDK를 완벽하게 지원하므로 데이터베이스와 직접 상호 작용할 수 있는 AI 에이전트를 만들 수 있습니다.

필수 조건

  • API 액세스가 가능한 OpenAI 계정
  • OpenAI Agents SDK 설치: pip install openai-agents
  • 실행 중인 DB MCP 서버 인스턴스(SSE 모드)

기본 통합 예제

DB MCP 서버를 OpenAI 에이전트와 통합하는 방법은 다음과 같습니다.

from openai import OpenAI from agents.agent import Agent, ModelSettings from agents.tools.mcp_server import MCPServerSse, MCPServerSseParams # Connect to the MCP server db_server = MCPServerSse( params=MCPServerSseParams( url="http://localhost:9095/sse", # URL to your running DB MCP server schema={ "params": { "type": "array", "items": { "type": "object", "properties": { "name": {"type": "string"}, "description": {"type": "string"}, "parameters": {"type": "object"} } } } } ), ) # Create the agent with access to database tools agent = Agent( name="Database Agent", model="gpt-4o", model_settings=ModelSettings(temperature=0.1), instructions=""" You are a database helper agent. You can execute SQL queries, manage database transactions, and explore schema information. """, mcp_servers=[db_server], ) # Now the agent can be used to interact with your databases through the OpenAI API

통합 테스트

저장소에는 OpenAI Agents SDK와의 호환성을 확인하기 위한 테스트 스크립트가 포함되어 있습니다.

# Run the test script ./test_tools/openai-agent-sdk-test/run_test.sh

스크립트는 다음을 수행합니다.

  1. 최신 변경 사항으로 서버를 빌드하세요
  2. 아직 실행 중이 아니면 서버를 시작하세요.
  3. OpenAI Agents SDK로 연결을 테스트합니다.
  4. 통합이 제대로 작동하는지 보고합니다.

에이전트 SDK 통합 문제 해결

문제가 발생하는 경우:

  1. 서버가 예상 포트에서 SSE 모드로 실행 중인지 확인하세요.
  2. OpenAI API 키가 환경 변수로 설정되어 있는지 확인하세요.
  3. 에이전트의 지침에 데이터베이스 도구가 구체적으로 언급되어 있는지 확인하십시오.
  4. 서버 로그에서 오류 메시지를 검사하세요.

스타 역사

ID: kdnbdf2y8p