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
동적 도구 생성
연결된 각 데이터베이스에 대해 서버는 자동으로 일련의 특수 도구를 생성합니다.
클린 아키텍처
서버는 다음 계층에 대해 클린 아키텍처 원칙을 따릅니다.
- 도메인 계층 : 핵심 비즈니스 엔터티 및 인터페이스
- 저장소 계층 : 데이터 액세스 구현
- 사용 사례 계층 : 애플리케이션 비즈니스 로직
- 전달 계층 : 외부 인터페이스(MCP 도구)
특징
- 동시 다중 데이터베이스 지원 : 여러 MySQL 및 PostgreSQL 데이터베이스에 동시에 연결하고 상호 작용합니다.
- 데이터베이스별 도구 생성 : 연결된 각 데이터베이스에 대한 특수 도구를 자동으로 생성합니다.
- 클린 아키텍처 : 관심사를 명확하게 분리한 모듈식 디자인
- OpenAI Agents SDK 호환성 : AI 어시스턴트와의 원활한 통합을 위해 OpenAI Agents SDK와 완벽하게 호환됩니다.
- 동적 데이터베이스 도구 :
- 매개변수를 사용하여 SQL 쿼리 실행
- 적절한 오류 처리를 통해 데이터 수정 문을 실행합니다.
- 세션 간 데이터베이스 트랜잭션 관리
- 데이터베이스 스키마와 관계 탐색
- 쿼리 성능을 분석하고 최적화 제안을 받습니다.
- 통합 인터페이스 : 다양한 데이터베이스 유형에서 일관된 상호 작용 패턴
- 연결 관리 : 여러 데이터베이스 연결을 위한 간단한 구성
현재 지원되는 데이터베이스
데이터 베이스 | 상태 | 특징 |
---|---|---|
MySQL | ✅ 전체 지원 | 쿼리, 트랜잭션, 스키마 분석, 성능 통찰력 |
포스트그레스큐엘 | ✅ 전체 지원(v9.6-17) | 쿼리, 트랜잭션, 스키마 분석, 성능 통찰력 |
빠른 시작
Docker 사용
가장 빠르게 시작하는 방법은 Docker를 사용하는 것입니다.
참고 : 컨테이너에 이미
/app/my-config.json
파일이 있으므로/app/config.json
에 마운트합니다. 플랫폼 불일치 경고가 발생하면--platform linux/amd64
또는--platform linux/arm64
옵션을 사용하여 플랫폼을 지정할 수 있습니다.
출처에서
서버 실행
서버는 다양한 사용 사례에 맞게 여러 전송 모드를 지원합니다.
STDIO 모드(IDE 통합용)
AI 코딩 어시스턴트와의 통합에 이상적:
출력은 JSON-RPC 메시지로 stdout으로 전송되고, 로그는 stderr로 전송됩니다.
커서 통합을 위해 .cursor/mcp.json
에 다음을 추가하세요.
SSE 모드(서버에서 보낸 이벤트)
웹 기반 애플리케이션 및 서비스의 경우:
이벤트 스트림을 위해 클라이언트를 http://localhost:9092/sse
에 연결합니다.
도커 컴포즈
데이터베이스 컨테이너가 있는 개발 환경의 경우 완전한 docker-compose.yml 파일을 제공합니다.
이 docker-compose 설정의 주요 기능:
- db-mcp-server 컨테이너는 시작하기 전에 모든 데이터베이스 서비스가 준비될 때까지 기다립니다.
- 여러 데이터베이스 유형과 버전이 포함되어 있습니다(MySQL 8.0, PostgreSQL 15, 16.3 및 17)
- 모든 데이터베이스에는 서버가 연결되기 전에 데이터베이스가 완전히 초기화되었는지 확인하기 위한 상태 검사가 포함되어 있습니다.
- 모든 데이터베이스 서비스에 대한 영구 볼륨
- 필요한 경우 직접 데이터베이스에 액세스할 수 있는 노출된 포트
설정은 wait-for-it.sh
스크립트를 사용하여 서버를 시작하기 전에 모든 데이터베이스 서비스가 완전히 준비되었는지 확인합니다. 이 스크립트는 진행하기 전에 TCP 호스트/포트를 사용할 수 있는지 확인합니다. 이 스크립트를 프로젝트 디렉터리에 포함해야 합니다. Docker 설정은 이 스크립트를 컨테이너에 마운트하고 데이터베이스 가용성을 확인하는 데 사용합니다.
이 설정을 사용하려면:
docker-compose.yml에 정의된 서비스와 일치하는 연결 세부 정보가 config.json 파일에 포함되어 있는지 확인하세요.
구성
데이터베이스 구성
데이터베이스 연결을 포함하는 config.json
파일을 만듭니다.
docker-compose 설정을 사용할 때 host
값이 docker-compose.yml 파일에 있는 서비스 이름과 일치해야 합니다.
명령줄 옵션
서버는 다양한 명령줄 옵션을 지원합니다.
사용 가능한 도구
연결된 각 데이터베이스(예: "mysql1", "mysql2")에 대해 서버는 다음을 생성합니다.
도구 명명 규칙
서버는 다음 형식을 따르는 이름을 가진 도구를 자동으로 생성합니다.
어디:
<tool_type>
: 쿼리, 실행, 트랜잭션, 스키마, 성능 중 하나<database_id>
: 구성에 정의된 데이터베이스의 ID
ID가 "mysql1"인 데이터베이스에 대한 도구 이름 예:
query_mysql1
execute_mysql1
transaction_mysql1
schema_mysql1
performance_mysql1
데이터베이스별 도구
query_<dbid>
: 지정된 데이터베이스에서 SQL 쿼리를 실행합니다.Copyexecute_<dbid>
: SQL 문(INSERT, UPDATE, DELETE)을 실행합니다.Copytransaction_<dbid>
: 데이터베이스 트랜잭션 관리Copyschema_<dbid>
: 데이터베이스 스키마 정보를 가져옵니다.Copyperformance_<dbid>
: 쿼리 성능 분석Copy
글로벌 도구
list_databases
: 구성된 모든 데이터베이스 연결을 나열합니다.Copy
예시
여러 데이터베이스 쿼리
거래 실행
로드맵
우리는 광범위한 데이터베이스 시스템을 지원하기 위해 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 - 분석 데이터베이스 지원
문제 해결
일반적인 문제
- 연결 오류 :
config.json
에서 데이터베이스 연결 설정을 확인하세요. - 도구를 찾을 수 없음 : 서버가 실행 중인지 확인하고 도구 이름 접두사를 확인하세요.
- 실패한 쿼리 : SQL 구문 및 데이터베이스 권한을 확인하세요.
- Docker 볼륨 마운트 오류 :
mountpoint for /app/config.json: not a directory
와 같은 오류가 표시되는 경우, 컨테이너가 해당 경로에 이미 파일을 가지고 있기 때문입니다. 다른 경로(예:/app/my-config.json
)에 마운트하고 구성을 그에 맞게 업데이트하세요. - 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"
- 환경 변수를 사용하세요:
- 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
플래그로 디버그 로깅을 활성화합니다.
기여하다
참여를 환영합니다! 다음과 같은 방법으로 도움을 주세요.
- 저장소를 포크하세요
- 기능 브랜치를 만듭니다 :
git checkout -b new-feature
- 변경 사항을 커밋하세요 :
git commit -am 'Add new feature'
- 브랜치에 푸시 :
git push origin new-feature
- 풀 리퀘스트 제출
귀하의 코드가 당사의 코딩 표준을 따르고 적절한 테스트를 포함하고 있는지 확인하세요.
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.
지원 및 연락처
- 질문이나 문제가 있으면 mnhatlinh.doan@gmail.com 으로 이메일을 보내주세요.
- 이슈를 직접 열어보세요: 이슈 트래커
- DB MCP Server가 귀하의 작업에 도움이 된다면 다음을 지원해 주시기 바랍니다.
커서 통합
도구 명명 규칙
MCP 서버는 Cursor가 예상하는 형식과 일치하는 이름으로 도구를 등록합니다. 도구 이름은 다음 형식을 따릅니다.
예: mcp_mysql1_db_mcp_server_stdio_schema_mysql1_db
서버는 기본적으로 mysql1_db_mcp_server_stdio
라는 이름을 사용하는데, 이는 mcp.json
파일의 커서 구성과 일치해야 합니다.
커서 구성
커서 구성( ~/.cursor/mcp.json
)에서 다음과 같은 구성이 있어야 합니다.
서버는 구성에 있는 데이터베이스 식별자와 일치하는 간단한 이름으로 도구를 자동으로 등록합니다.
커서에서 MCP 도구 사용
DB MCP 서버가 실행되고 Cursor에서 제대로 구성되면 AI 어시스턴트 대화에서 MCP 도구를 사용할 수 있습니다. 도구는 다음과 같은 명명 패턴을 따릅니다.
어디:
<server_name>
은 .cursor/mcp.json에 정의된 이름입니다(예: "multidb").<tool_type>
은 다음 중 하나입니다: 쿼리, 실행, 트랜잭션, 스키마, 성능, 목록_데이터베이스<database_id>
는 구성의 데이터베이스 ID입니다(list_databases에는 필요하지 않음).
예:
데이터베이스 ID가 "mysql1"인 "multidb"라는 서버의 경우:
- 모든 데이터베이스 나열 :
- 데이터베이스 쿼리 :
- 데이터베이스 스키마 보기 :
- 실행 명령문 :
- 거래 관리 :
커서에서 MCP 도구 문제 해결
AI 어시스턴트가 MCP 도구를 호출할 수 없는 경우:
- 서버가 실행 중인지 확인하세요(
ps aux | grep server
로 확인) - .cursor/mcp.json 구성이 올바른지 확인하세요.
- .env의 server_name이 MCP 도구 호출에 있는 내용과 일치하는지 확인하세요.
- 구성 변경 후 커서를 다시 시작합니다.
- 오류가 있는지 로그/ 디렉토리의 로그를 확인하세요.
OpenAI 에이전트 SDK 통합
DB MCP 서버는 OpenAI의 Agents SDK를 완벽하게 지원하므로 데이터베이스와 직접 상호 작용할 수 있는 AI 에이전트를 만들 수 있습니다.
필수 조건
- API 액세스가 가능한 OpenAI 계정
- OpenAI Agents SDK 설치:
pip install openai-agents
- 실행 중인 DB MCP 서버 인스턴스(SSE 모드)
기본 통합 예제
DB MCP 서버를 OpenAI 에이전트와 통합하는 방법은 다음과 같습니다.
통합 테스트
저장소에는 OpenAI Agents SDK와의 호환성을 확인하기 위한 테스트 스크립트가 포함되어 있습니다.
스크립트는 다음을 수행합니다.
- 최신 변경 사항으로 서버를 빌드하세요
- 아직 실행 중이 아니면 서버를 시작하세요.
- OpenAI Agents SDK로 연결을 테스트합니다.
- 통합이 제대로 작동하는지 보고합니다.
에이전트 SDK 통합 문제 해결
문제가 발생하는 경우:
- 서버가 예상 포트에서 SSE 모드로 실행 중인지 확인하세요.
- OpenAI API 키가 환경 변수로 설정되어 있는지 확인하세요.
- 에이전트의 지침에 데이터베이스 도구가 구체적으로 언급되어 있는지 확인하십시오.
- 서버 로그에서 오류 메시지를 검사하세요.
스타 역사
This server cannot be installed
Multi DB MCP 서버는 AI 에이전트와 데이터베이스의 상호 작용 방식을 혁신하도록 설계된 데이터베이스 모델 컨텍스트 프로토콜(DMP)의 고성능 구현입니다. 현재 MySQL과 PostgreSQL 데이터베이스를 지원합니다.