Doris MCP 服务器

Doris MCP（模型控制面板）服务器是一个使用 Python 和 FastAPI 构建的后端服务。它实现了 MCP（模型控制面板）协议，允许客户端通过定义的“工具”与其交互。它主要设计用于连接到 Apache Doris 数据库，并可能利用大型语言模型 (LLM) 来执行诸如将自然语言查询转换为 SQL (NL2SQL)、执行查询以及进行元数据管理和分析等任务。

核心特性

• MCP 协议实现：提供标准的 MCP 接口，支持工具调用、资源管理和提示交互。
• 多种通信模式：
  • SSE（服务器发送事件）：通过 /sse（初始化）和 /mcp/messages（通信）端点提供 (src/sse_server.py)。
  • 可流式 HTTP：通过统一的 /mcp 端点提供，支持请求/响应和流式处理 (src/streamable_server.py)。
  • （可选）标准输入输出：可以通过标准输入输出进行交互 (src/stdio_server.py)，需要特定的启动配置。
• 基于工具的接口：核心功能被封装成 MCP 工具，客户端可以根据需要调用。目前可用的关键工具侧重于直接数据库交互：
  • SQL 执行 (mcp_doris_exec_query)
  • 数据库和表列表 (mcp_doris_get_db_list, mcp_doris_get_db_table_list)
  • 元数据检索 (mcp_doris_get_table_schema, mcp_doris_get_table_comment, mcp_doris_get_table_column_comments, mcp_doris_get_table_indexes)
  • 审计日志检索 (mcp_doris_get_recent_audit_logs) 注意：当前工具主要关注直接的数据库操作。
• 数据库交互：提供连接到 Apache Doris（或其他兼容数据库）并执行查询的功能 (src/utils/db.py)。
• 灵活配置：通过 .env 文件配置，支持数据库连接设置、LLM 提供者/模型、API 密钥、日志级别等。
• 元数据提取：能够提取数据库元数据信息 (src/utils/schema_extractor.py)。

系统要求

• Python 3.12+
• 数据库连接详情（例如，Doris 主机名、端口、用户名、密码、数据库）

快速开始

1. 克隆仓库

bash

如果不同，请替换为实际的仓库 URL

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

2. 安装依赖

bash pip install -r requirements.txt

3. 配置环境变量

将 .env.example 文件复制为 .env 并根据您的环境修改设置：

bash cp .env.example .env

关键环境变量：

• 数据库连接：
  • DB_HOST: 数据库主机名
  • DB_PORT: 数据库端口（默认 9030）
  • DB_USER: 数据库用户名
  • DB_PASSWORD: 数据库密码
  • DB_DATABASE: 默认数据库名称
• 服务器配置：
  • SERVER_HOST: 服务器监听的主机地址（默认 0.0.0.0）
  • SERVER_PORT: 服务器监听的端口（默认 3000）
  • ALLOWED_ORIGINS: CORS 允许的来源（逗号分隔，* 允许所有）
  • MCP_ALLOW_CREDENTIALS: 是否允许 CORS 凭证（默认 false）
• 日志配置：
  • LOG_DIR: 日志文件目录（默认 ./logs）
  • LOG_LEVEL: 日志级别（例如 INFO, DEBUG, WARNING, ERROR，默认 INFO）
  • CONSOLE_LOGGING: 是否将日志输出到控制台（默认 false）

可用的 MCP 工具

下表列出了当前可通过 MCP 客户端调用的主要工具：

| 工具名称 | 描述 | 参数 | 状态 || :-------------------------------- | :---------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | :------- | | mcp_doris_get_db_list | 获取服务器上所有数据库名称的列表。 | random_string (字符串, 必需) | ✅ 活跃 | | mcp_doris_get_db_table_list | 获取指定数据库中所有表名称的列表。 | random_string (字符串, 必需), db_name (字符串, 可选, 默认为当前数据库) | ✅ 活跃 | | mcp_doris_get_table_schema | 获取指定表的详细结构。 | random_string (字符串, 必需), table_name (字符串, 必需), db_name (字符串, 可选) | ✅ 活跃 | | mcp_doris_get_table_comment | 获取指定表的注释。 | random_string (字符串, 必需), table_name (字符串, 必需), db_name (字符串, 可选) | ✅ 活跃 | | mcp_doris_get_table_column_comments | 获取指定表中所有列的注释。 | random_string (字符串, 必需), table_name (字符串, 必需), db_name (字符串, 可选) | ✅ 活跃 | | mcp_doris_get_table_indexes | 获取指定表的索引信息。 | random_string (字符串, 必需), table_name (字符串, 必需), db_name (字符串, 可选) | ✅ 活跃 | | mcp_doris_exec_query | 执行 SQL 查询并返回结果命令。 | random_string (字符串, 必需), sql (字符串, 必需), db_name (字符串, 可选), max_rows (整数, 可选, 默认 100), timeout (整数, 可选, 默认 30) | ✅ 活跃 | | mcp_doris_get_recent_audit_logs | 获取最近一段时间内的审计日志记录。 | random_string (字符串, 必需), days (整数, 可选, 默认 7), limit (整数, 可选, 默认 100) | ✅ 活跃 |

注意： 所有工具都需要一个 random_string 参数作为调用标识符，通常由 MCP 客户端自动处理。“可选”和“必需”指的是工具内部逻辑；根据客户端实现的不同，可能需要提供所有参数的值。这里列出的工具名称是基本名称；根据连接模式，客户端可能会看到它们带有前缀（例如 mcp_doris_stdio3_get_db_list）。

4. 运行服务

如果您使用 SSE 模式，请执行以下命令：

bash ./start_server.sh

此命令将启动 FastAPI 应用程序，默认同时提供 SSE 和 Streamable HTTP MCP 服务。

服务端点：

• SSE 初始化: http://<host>:<port>/sse
• SSE 通信: http://<host>:<port>/mcp/messages (POST)
• Streamable HTTP: http://<host>:<port>/mcp (支持 GET, POST, DELETE, OPTIONS)
• 健康检查: http://<host>:<port>/health
• (潜在) 状态检查: http://<host>:<port>/status (确认是否在 main.py 中实现)

使用方法

与 Doris MCP 服务器交互需要一个 MCP 客户端。客户端连接到服务器的 SSE 或 Streamable HTTP 端点，并根据 MCP 规范发送请求（如 tool_call）来调用服务器上的工具。

主要交互流程：

1. 客户端初始化：连接到 /sse (SSE) 或向 /mcp 发送 initialize 方法调用 (Streamable)。

2. （可选）发现工具：客户端可以调用 mcp/listTools 或 mcp/listOfferings 来获取支持的工具列表、其描述和参数模式。

3. 调用工具：客户端发送 tool_call 消息/请求，指定 tool_name 和 arguments。

   • 示例：获取表结构
     • tool_name: mcp_doris_get_table_schema (或特定模式的名称)* arguments: 包含 random_string, table_name, db_name。

4. 处理响应:

   • 非流式: 客户端接收包含 result 或 error 的响应。
   • 流式: 客户端先接收一系列 tools/progress 通知，然后是包含 result 或 error 的最终响应。

具体的工具名称和参数应从 src/tools/ 代码中引用或通过 MCP 发现机制获取。

使用 Cursor 连接

你可以使用 Stdio 模式或 SSE 模式将 Cursor 连接到此 MCP 服务器。

Stdio 模式

Stdio 模式允许 Cursor 直接管理服务器进程。配置在 Cursor 的 MCP 服务器设置文件中完成（通常是 ~/.cursor/mcp.json 或类似文件）。

如果你使用 stdio 模式，请执行以下命令来下载并构建环境依赖包，但请注意你需要将项目路径更改为正确的路径地址：

bash uv --project /your/path/doris-mcp-server run doris-mcp

1. 配置 Cursor: 在你的 Cursor MCP 配置中添加如下条目：

   json { "mcpServers": { "doris-stdio": { "command": "uv", "args": ["--project", "/path/to/your/doris-mcp-server", "run", "doris-mcp"], "env": { "DB_HOST": "127.0.0.1", "DB_PORT": "9030", "DB_USER": "root", "DB_PASSWORD": "your_db_pa…