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 提供以下主要功能：

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），提供四级安全级别。
   • 内置 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. 元数据探索

   • 数据工程师可快速获取数据库 schema、表结构和索引信息，加速数据建模和优化。

3. AI 驱动的业务智能

   • 集成 AI 代理（如 Claude、Cursor），通过 MCP 协议实现自动化数据查询和分析工作流。

4. 安全合规性管理

   • 企业级安全框架和审计日志功能，满足金融、医疗等行业对数据安全和合规性的要求。

5. 多目录环境

   • 支持多目录联合，适合复杂数据仓库环境中的元数据管理和查询。

项目优势与局限性

优势

• 智能化：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、元数据管理、安全性和性能优化等特性使其在实时数据分析、业务智能和企业级应用中具有广泛潜力。