Home
Login
apache/doris-mcp-serverPlease refer to the latest official releases for information GitHub Homepage

Apache Doris MCP 서버는 Python 및 FastAPI 기반 백엔드 서비스로, 모델 컨텍스트 프로토콜(MCP)을 지원하여 Apache Doris 데이터베이스에 연결하고 자연어-SQL(NL2SQL) 변환, 쿼리 실행 및 메타데이터 관리를 구현합니다.

Apache-2.0Python 94apachedoris-mcp-server Last Updated: 2025-06-23

Apache Doris MCP 서버 프로젝트 상세 소개

프로젝트 개요

Apache Doris MCP(Model Context Protocol) 서버는 Python과 FastAPI를 기반으로 구축된 백엔드 서비스로, 모델 컨텍스트 프로토콜(MCP)을 통해 Apache Doris 데이터베이스와 원활하게 통합되도록 설계되었습니다. AI 에이전트 및 클라이언트에 표준화된 인터페이스를 제공하여 자연어-SQL 변환(NL2SQL), SQL 쿼리 실행, 메타데이터 관리 및 데이터 분석 등의 기능을 지원합니다. 이 프로젝트는 Apache Doris 커뮤니티의 중요한 확장이며, 특히 효율적인 데이터 상호 작용과 지능형 분석이 필요한 비즈니스 시나리오에 적합합니다.

2025년 0.3.0 버전 출시 이후, 프로젝트는 SSE(Server-Sent Events) 기반 통신에서 통합된 Streamable HTTP 프로토콜로의 마이그레이션, 엔터프라이즈급 보안 프레임워크 추가, 성능 최적화 기능 등 중요한 아키텍처 업데이트를 거쳤습니다. 프로젝트의 핵심 목표는 MCP 프로토콜을 통해 AI 시스템과 Apache Doris 데이터베이스를 연결하여 지능적인 데이터 탐색 및 분석을 구현하는 것입니다.

핵심 기능

Apache Doris MCP 서버는 다음과 같은 주요 기능을 제공합니다.

  1. 자연어-SQL 변환(NL2SQL)

    • 자연어 입력을 통해 SQL 쿼리 생성을 지원하며, 대규모 언어 모델(LLMs)과 결합하여 지능적인 쿼리 생성을 구현합니다.
    • 비즈니스 사용자가 복잡한 SQL을 작성하지 않고도 데이터를 쿼리할 수 있는 시나리오에 적합합니다.

  2. SQL 쿼리 실행

    • exec_query 도구를 통해 SQL 명령을 직접 실행할 수 있으며, 데이터베이스 선택, 행 수 제한 및 시간 초과 설정을 사용자 정의할 수 있습니다.
    • 내장된 보안 검사(예: SQL 주입 방지) 및 자동 LIMIT 추가를 통해 쿼리 보안 및 효율성을 보장합니다.

  3. 메타데이터 관리

    • 다음과 같은 풍부한 메타데이터 추출 도구를 제공합니다.
      • 모든 데이터베이스 및 테이블 나열(get_all_databases, get_database_tables).
      • 테이블 구조, 주석 및 인덱스 정보 가져오기(get_table_schema, get_table_comment, get_column_comments, get_table_indexes).
      • 다중 카탈로그(Catalog) 검색 지원(get_catalog_list).

  4. 감사 로그 쿼리

    • get_recent_audit_logs를 통해 최근 감사 기록을 가져오고, 사용자 정의 시간 범위 및 기록 제한을 지원합니다.

  5. 엔터프라이즈급 보안 프레임워크

    • 다양한 인증 방식(Token, Basic Auth, OAuth)을 지원합니다.
    • 역할 기반 접근 제어(RBAC)를 통해 4단계 보안 수준을 제공합니다.
    • 내장된 SQL 주입 방지, 쿼리 검증 및 데이터 마스킹 기능을 제공합니다.

  6. 성능 최적화

    • 쿼리 실행 최적화, 향상된 캐시 메커니즘 및 연결 풀 관리를 통해 성능을 향상시킵니다.
    • 성능 모니터링 및 통계 분석을 지원합니다(performance_stats).

  7. 다중 통신 모드

    • Streamable HTTP: 통합된 /mcp 엔드포인트를 통해 요청/응답 및 스트리밍 전송을 지원합니다(src/streamable_server.py).
    • SSE (더 이상 사용되지 않음): 초기 버전에서는 /sse 및 /mcp/messages 엔드포인트를 통해 통신을 지원했습니다(src/sse_server.py).
    • Stdio (선택 사항): 표준 입력/출력을 통해 상호 작용합니다(src/stdio_server.py).

  8. 실험적 기능

    • 열 통계 분석(column_analysis)을 통해 데이터 통찰력을 제공합니다.
    • 카탈로그 연합 지원은 다중 카탈로그 환경에 적합합니다.

기술 아키텍처

프로젝트의 아키텍처 설계는 모듈화되고 효율적이며, 다음과 같은 주요 구성 요소를 포함합니다.

  • 핵심 프레임워크: Python 3.12 및 FastAPI를 기반으로 구축되어 고성능 API 서비스를 제공합니다.
  • MCP 프로토콜 구현:
    • 표준화된 도구 호출, 리소스 관리 및 프롬프트 상호 작용 인터페이스를 제공합니다.
    • 통합된 /mcp 엔드포인트를 통해 모든 요청을 처리하여 통합을 단순화합니다.
  • 데이터베이스 상호 작용:
    • doris_mcp_server/utils/db.py: 데이터베이스 연결(get_db_connection) 및 쿼리 실행(execute_query, execute_query_df) 기능을 제공합니다.
    • doris_mcp_server/utils/schema_extractor.py: MetadataExtractor 클래스는 메타데이터 추출을 담당하며, 캐시 메커니즘을 포함합니다.
    • doris_mcp_server/utils/sql_executor_tools.py: execute_sql_query 함수는 쿼리 로직을 캡슐화하며, 보안 검사 및 결과 직렬화를 포함합니다.
  • 보안 관리:
    • 다중 인증 방식 및 RBAC를 지원합니다.
    • SQL 주입 방지, 쿼리 검증 및 감사 로그 기록을 제공합니다.
  • 배포 지원:
    • Docker 이미지화 배포, 통합 포트 구성(3000, 3001, 3002).
    • 환경 변수 구성(예: DB_HOST, DB_PORT, DB_USER, DB_PASSWORD).

아키텍처 변경: 0.3.0 버전에서는 약 300줄의 SSE 레거시 코드를 제거하고 Streamable HTTP로 마이그레이션하여 도구 이름을 통합하고(mcp_doris_ 접두사 제거) 모듈화 정도를 높였습니다.

설치 및 사용

환경 요구 사항

  • Python 3.12 이상
  • Apache Doris 데이터베이스 (MySQL 프로토콜을 통해 연결)
  • 패키지 관리 도구 (예: uv 또는 pip)
  • 선택 사항: Docker (컨테이너화 배포용)

설치 단계

  1. 저장소 복제:

    git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server

  2. 종속성 설치: uv (권장) 또는 pip를 사용하여 설치합니다.

    uv sync

    또는

    pip install -r requirements.txt

  3. 환경 변수 구성: .env 파일을 생성하거나 환경 변수를 직접 설정합니다.

    export DORIS_HOST=<doris-host>
export DORIS_PORT=<port>
export DORIS_USER=<doris-user>
export DORIS_PASSWORD=<doris-pwd>
export SERVER_PORT=3000

  4. 서버 시작:

    uv run --with mcp-doris --python 3.13 mcp-doris

    또는

    python -m mcp_doris.mcp_server

  5. 시작 확인: 시작에 성공하면 MCP 클라이언트(예: Cursor) 또는 내장된 MCP 브라우저(http://localhost:5173)를 통해 상호 작용할 수 있습니다.

연결 테스트

테스트 스크립트를 실행하여 데이터베이스 연결을 확인합니다.

python src/doris-mcp-server/test.py

예상 출력:

🚀 Doris MCP Server is starting...
[DorisConnector] Connected to 127.0.0.1:9030
✅ Database connection successful.
[DorisConnector] Connection closed.

활용 시나리오

  1. 실시간 데이터 분석

    • NL2SQL 기능을 결합하여 비즈니스 사용자는 자연어를 통해 실시간 데이터를 쿼리하고 보고서 또는 대시보드를 생성할 수 있습니다.
    • 소매, 금융, 통신 등 산업의 실시간 의사 결정 지원에 적합합니다.

  2. 메타데이터 탐색

    • 데이터 엔지니어는 데이터베이스 스키마, 테이블 구조 및 인덱스 정보를 빠르게 가져와 데이터 모델링 및 최적화를 가속화할 수 있습니다.

  3. AI 기반 비즈니스 인텔리전스

    • AI 에이전트(예: Claude, Cursor)를 통합하여 MCP 프로토콜을 통해 자동화된 데이터 쿼리 및 분석 워크플로를 구현합니다.

  4. 보안 규정 준수 관리

    • 엔터프라이즈급 보안 프레임워크 및 감사 로그 기능은 금융, 의료 등 산업의 데이터 보안 및 규정 준수 요구 사항을 충족합니다.

  5. 다중 카탈로그 환경

    • 다중 카탈로그 연합을 지원하여 복잡한 데이터 웨어하우스 환경의 메타데이터 관리 및 쿼리에 적합합니다.

프로젝트 장점 및 한계

장점

  • 지능화: NL2SQL 및 LLM 통합으로 데이터 쿼리 장벽을 낮춥니다.
  • 보안성: 다중 인증, RBAC 및 SQL 보호를 통해 엔터프라이즈급 보안을 보장합니다.
  • 고성능: 캐시, 연결 풀 및 쿼리 최적화를 통해 효율성을 향상시킵니다.
  • 유연성: 다양한 통신 모드 및 모듈화된 도구 확장을 지원합니다.

한계

  • 초기 버전 안정성: 일부 기능(예: column_analysis)은 실험적이며 버그가 있을 수 있습니다.
  • Doris 데이터베이스 종속성: 주로 Apache Doris를 위해 설계되었으며, 다른 MySQL 프로토콜 데이터베이스와의 호환성은 제한적입니다.
  • SSE 폐기: 0.3.0 버전에서는 SSE 지원이 제거되었으므로 Streamable HTTP로 마이그레이션해야 합니다.

결론

Apache Doris MCP 서버는 Apache Doris 데이터베이스와 AI 기반 분석 요구 사항을 연결하는 강력하고 유연한 도구입니다. NL2SQL, 메타데이터 관리, 보안 및 성능 최적화와 같은 기능은 실시간 데이터 분석, 비즈니스 인텔리전스 및 엔터프라이즈급 애플리케이션에서 광범위한 잠재력을 제공합니다.

Star History Chart