Apache Doris MCP Server 項目詳細介紹

項目概述

Apache Doris MCP（Model Context Protocol）Server 是一個基於 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 Server 提供以下主要功能：

自然語言轉 SQL（NL2SQL）
- 支持通過自然語言輸入生成 SQL 查詢，結合大型語言模型（LLMs）實現智能化查詢生成。
- 適用於業務用戶無需編寫複雜 SQL 即可查詢數據的場景。
SQL 查詢執行
- 通過 exec_query 工具支持直接執行 SQL 命令，可自定義資料庫選擇、行數限制和超時設置。
- 內置安全檢查（如 SQL 注入防護）和自動 LIMIT 添加，確保查詢安全性和效率。
元數據管理
- 提供豐富的元數據提取工具，包括：
  - 列出所有資料庫和表（get_all_databases, get_database_tables）。
  - 獲取表結構、註釋和索引信息（get_table_schema, get_table_comment, get_column_comments, get_table_indexes）。
  - 支持多目錄（Catalog）發現（get_catalog_list）。
審計日誌查詢
- 通過 get_recent_audit_logs 獲取最近的審計記錄，支持自定義時間範圍和記錄限制。
企業級安全框架
- 支持多種認證方式（Token、Basic Auth、OAuth）。
- 基於角色的訪問控制（RBAC），提供四級安全級別。
- 內置 SQL 注入防護、查詢驗證和數據脫敏功能。
性能優化
- 查詢執行優化，通過增強的緩存機制和連接池管理提升性能。
- 支持性能監控和統計分析（performance_stats）。
多通信模式
- Streamable HTTP：通過統一的 /mcp 端點支持請求/響應和流式傳輸（src/streamable_server.py）。
- SSE（已廢棄）：早期版本支持通過 /sse 和 /mcp/messages 端點通信（src/sse_server.py）。
- Stdio（可選）：通過標準輸入/輸出交互（src/stdio_server.py）。
實驗性功能
- 列統計分析（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（用於容器化部署）

安裝步驟

克隆倉庫：

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

安裝依賴：
使用 uv（推薦）或 pip 安裝：
```
uv sync
```
或
```
pip install -r requirements.txt
```

配置環境變量：
創建 .env 文件或直接設置環境變量：

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

啟動伺服器：

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

或

python -m mcp_doris.mcp_server

驗證啟動：
啟動成功後，可通過 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.

應用場景

實時數據分析
- 結合 NL2SQL 功能，業務用戶可通過自然語言查詢實時數據，生成報表或儀表盤。
- 適用於零售、金融、電信等行業的實時決策支持。
元數據探索
- 數據工程師可快速獲取資料庫 schema、表結構和索引信息，加速數據建模和優化。
AI 驅動的業務智能
- 集成 AI 代理（如 Claude、Cursor），通過 MCP 協議實現自動化數據查詢和分析工作流。
安全合規性管理
- 企業級安全框架和審計日誌功能，滿足金融、醫療等行業對數據安全和合規性的要求。
多目錄環境
- 支持多目錄聯合，適合複雜數據倉庫環境中的元數據管理和查詢。

項目優勢與局限性

優勢

智能化：NL2SQL 和 LLM 集成降低數據查詢門檻。
安全性：多認證、RBAC 和 SQL 防護確保企業級安全。
高性能：緩存、連接池和查詢優化提升效率。
靈活性：支持多種通信模式和模塊化工具擴展。

局限性

早期版本穩定性：部分功能（如 column_analysis）為實驗性，可能存在 bug。
依賴 Doris 資料庫：主要為 Apache Doris 設計，兼容其他 MySQL 協議資料庫的能力有限。
SSE 廢棄：0.3.0 版本移除 SSE 支持，需遷移至 Streamable HTTP。

總結

Apache Doris MCP Server 是一個功能強大且靈活的工具，橋接了 Apache Doris 資料庫與 AI 驅動的分析需求。其 NL2SQL、元數據管理、安全性和性能優化等特性使其在實時數據分析、業務智能和企業級應用中具有廣泛潛力。