Apache Doris 实战教程：从零搭建 MCP Server，让 AI Agent 直接用自然语言查数据

SelectDB 刚在 2026 AI 发布会上推出 MCP Server + 语义层，本文手把手带你部署配置。写完这篇，你的 Claude Code/Cursor 就能用自然语言直接查 Doris 里的数据了。

关键词：Apache Doris · SelectDB · MCP Server · 语义层 · Claude Code · 自然语言查询 · AI 数据分析 · 实战教程

先看效果

配置完成后，在 Claude Code 中可以直接这样对话：

erlang 复制代码

👤 你：上周各渠道的 DAU 趋势怎么样？

🤖 Agent：让我查一下...
  查询了 analytics_db.user_behavior 表
  上周日活用户 45.2 万，环比增长 3.7%
  organic 渠道占比最高（42%），paid_search 增速最快（+12%）

不再需要手写 SQL、手动导出 CSV、复制到 Excel------直接自然语言对话。

第一步：环境准备

bash 复制代码

# 确认 Python 版本
python3 --version  # 需要 >= 3.9

# 创建虚拟环境
python3 -m venv selectdb-mcp-env
source selectdb-mcp-env/bin/activate

# 安装 MCP Server
pip install selectdb-mcp-server

确认 Doris 集群可连接（默认 MySQL 协议，端口 9030）：

bash 复制代码

mysql -h <你的Doris FE地址> -P 9030 -u root -p

第二步：启动 MCP Server

bash 复制代码

# 启动 MCP Server（stdio 模式，供 Agent 客户端使用）
selectdb-mcp serve \
  --host 127.0.0.1 \
  --port 9030 \
  --user root \
  --password your_password \
  --database analytics_db

服务启动后，MCP Server 会在标准输入输出上监听 Agent 请求。

第三步：配置 Claude Code 连接 MCP Server

在 Claude Code 的 MCP 配置文件中添加 SelectDB 连接：

json 复制代码

{
  "mcpServers": {
    "selectdb": {
      "command": "selectdb-mcp",
      "args": [
        "serve",
        "--host", "your-doris-fe:9030",
        "--user", "root",
        "--password", "your_password",
        "--database", "analytics_db"
      ]
    }
  }
}

配置文件路径：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
或通过 Claude Code 设置界面添加

配置完成后重启 Claude Code，在对话中可以看到 SelectDB 工具已被加载。

第四步：定义语义层------核心步骤

语义层让 Agent 理解业务，而不是瞎猜字段含义。

4.1 创建语义层配置

yaml 复制代码

# analytics_semantic.yaml
catalog: analytics_db

dimensions:
  - name: channel
    description: "用户来源渠道：organic(自然流量)、paid_search(付费搜索)、social_media(社交媒体)、referral(推荐)"
    source: user_profile.channel

  - name: user_type
    description: "用户类型：new(新用户)、active(活跃用户)、churned(流失用户)"
    source: user_profile.user_type

  - name: date
    description: "日期维度，支持按天/周/月聚合"
    source: user_behavior.event_date

metrics:
  - name: dau
    description: "日活跃用户数，当天至少有一次行为的独立用户"
    expression: "COUNT(DISTINCT user_id)"
    source: user_behavior

  - name: mau
    description: "月活跃用户数，当月至少有一次行为的独立用户"
    expression: "COUNT(DISTINCT user_id)"
    source: user_behavior

  - name: retention_7d
    description: "7日留存率，新用户在第7天仍然活跃的比例"
    expression: >
      COUNT(DISTINCT CASE WHEN day7_active THEN user_id END)
      * 1.0 / NULLIF(COUNT(DISTINCT user_id), 0)
    source: user_retention

  - name: avg_session_minutes
    description: "平均会话时长（分钟）"
    expression: "AVG(session_duration_sec) / 60.0"
    source: user_behavior

  - name: conversion_rate
    description: "支付转化率，完成购买的用户占活跃用户比例"
    expression: >
      COUNT(DISTINCT CASE WHEN event_type = 'purchase' THEN user_id END)
      * 1.0 / NULLIF(COUNT(DISTINCT user_id), 0)
    source: user_behavior

relationships:
  - left: user_behavior.user_id
    right: user_profile.user_id
    type: many_to_one
    description: "用户行为关联用户画像"

4.2 加载语义层到 SelectDB

bash 复制代码

# 上传语义层到 Doris
selectdb-mcp semantic load --file analytics_semantic.yaml

# 验证加载结果
selectdb-mcp semantic list

输出示例：

bash 复制代码

📊 已加载指标 (5):
  dau             ─ 日活跃用户数（DAU）
  mau             ─ 月活跃用户数（MAU）
  retention_7d    ─ 7日留存率
  avg_session_minutes ─ 平均会话时长
  conversion_rate ─ 支付转化率

📏 已加载维度 (3):
  channel         ─ 用户来源渠道
  user_type       ─ 用户类型
  date            ─ 日期维度

🔗 已加载关系 (1):
  user_behavior.user_id → user_profile.user_id

第五步：测试自然语言查询

测试 1：单指标查询

在 Claude Code 中：

复制代码

问：昨天各渠道的 DAU 是多少？

Agent 自动生成并执行：

sql 复制代码

-- Agent 内部生成的 SQL（用户可见）
SELECT
    p.channel,
    COUNT(DISTINCT b.user_id) AS dau
FROM user_behavior b
LEFT JOIN user_profile p ON b.user_id = p.user_id
WHERE b.event_date = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY)
GROUP BY p.channel
ORDER BY dau DESC;

测试 2：复杂多指标查询

复制代码

问：上个月 organic 渠道新用户的 7 日留存率和平均会话时长？

Agent 处理逻辑：

识别指标："7 日留存率" → retention_7d，"平均会话时长" → avg_session_minutes
识别维度过滤："organic" → channel = 'organic'，"新用户" → user_type = 'new'
识别时间范围："上个月" → 当前月减 1
自动 Join 三张表

第六步：高级场景------自定义 Skill

除了数据查询，SelectDB 还发布了 CI/Skill 体系。以"慢查询诊断"Skill 为例：

python 复制代码

# slow_query_skill.py ------ 自定义慢查询诊断 Skill
# 这个脚本通过 MCP Server 暴露为 Agent 可调用的工具

class SlowQueryDiagnoseSkill:
    """慢查询自动诊断 Skill"""

    def run(self, limit: int = 10):
        """获取并分析 Top N 慢查询"""
        sql = f"""
        SELECT
            query_id,
            query_time_ms,
            scan_rows,
            return_rows,
            LEFT(query_text, 200) AS query_preview
        FROM information_schema.query_log
        WHERE query_time_ms > 1000
        ORDER BY query_time_ms DESC
        LIMIT {limit}
        """
        # 通过 MCP 执行查询
        result = self.mcp_client.execute(sql)

        # 生成诊断建议
        suggestions = []
        for row in result:
            if row['scan_rows'] > row['return_rows'] * 100:
                suggestions.append({
                    'query_id': row['query_id'],
                    'issue': '扫描行数远大于返回行数，缺少索引或分区裁剪',
                    'suggestion': '检查 WHERE 条件是否命中分区 Key，或添加物化视图'
                })
        return suggestions

在 Claude Code 中触发：

复制代码

问：帮我检查下最近有没有慢查询

Agent 自动调用 slow_query_diagnose Skill 并返回结果。

第七步：部署检查

bash 复制代码

# 确认 MCP Server 正常运行
curl http://localhost:9030/api/health

# 确认语义层已加载
selectdb-mcp semantic list

# 测试 Agent 查询（在 Claude Code 中）
# 👤 查看 analytics_db 中有哪些指标
# 预期：Agent 应列出语义层中定义的所有指标

常见问题

Q：MCP Server 连接失败？ A：检查三项：① Doris FE 端口是否可达（默认 9030，MySQL 协议）② 用户是否有该 Database 的 SELECT 权限 ③ Python 依赖是否完整（pip list | grep selectdb）

Q：Agent 生成的 SQL 不准确？ A：通常是因为语义层定义不够细。建议：① 为每个指标添加明确的 description ② 补充表关系（relationships）③ 对于复杂指标，在 expression 中使用子查询或更精确的逻辑

Q：可以用在其他 Agent 上吗？ A：可以。MCP 是开放协议，Cursor、Codex 以及任何支持 MCP 的客户端都可以使用相同配置接入。

相关阅读推荐：

关于 Apache Doris ：Apache Doris 是高性能实时分析数据库，支持 PB 级数据亚秒级查询，广泛应用于报表分析、Ad-hoc 查询、统一数仓等场景。SelectDB 是 Apache Doris 的商业化公司，提供企业级支持和云服务。欢迎加入 Doris 社区交流更多实践。