使用 MCP Server 连接 AI 客户端-云数据库 SelectDB 版(SelectDB)-阿里云帮助中心

通过 MCP（Model Context Protocol）Server 服务，可以将云数据库 SelectDB 版的 Serverless 实例接入 Claude Code、Cursor 等 AI 编程助手，使 AI 客户端通过自然语言直接查询和分析 SelectDB 中的数据。

适用范围

已创建 SelectDB Serverless 实例。MCP Server 功能仅适用于 Serverless 类型，存算一体实例暂不支持。
实例所在地域已支持 MCP Server 功能。

开通 MCP Server 服务

登录 SelectDB 控制台。
在实例列表，单击目标 Serverless 实例名称。
在左侧导航栏，单击 MCP 服务。
在 MCP Server 页面，单击开启服务。
确认弹窗中，单击确定。

开通请求提交后，系统自动创建 MCP Server 服务，创建过程通常需要数分钟。页面自动刷新服务状态，无需手动操作。服务创建完成后，系统自动进入 IP 白名单检测流程。

添加 IP 白名单

服务激活后，系统自动检测当前公网 IP 地址，并判断该 IP 是否已纳入实例白名单：

如果当前 IP 已纳入白名单，页面直接显示 MCP 服务的网络信息和接入指南。
如果当前 IP 未纳入白名单，系统弹出提示，单击确定可将当前公网 IP 自动添加到白名单分组中。添加成功后即可查看服务信息。

获取连接地址

MCP Server 服务激活且 IP 白名单配置完成后，页面将显示以下网络信息：

信息项	说明
WebUI 地址	MCP Server 的 Web 管理界面地址，可通过浏览器打开进行可视化管理。
MCP 服务地址	AI 客户端接入 MCP Server 时使用的服务端点地址。

配置 AI 客户端

获取 MCP 服务地址后，可使用 SelectDB 实例的数据库账号和密码配置 AI 客户端连接。以下以 Claude Code 和 Cursor 为例说明配置方法。

Claude Code

打开终端，执行以下命令，将 SelectDB MCP Server 添加为 Claude Code 的数据源：
```
claude mcp add --transport http selectdb <MCP服务地址> \
  --header "Authorization: Bearer <用户名>:<密码>"
```
<MCP服务地址> 替换为控制台显示的 MCP 服务地址，<用户名> 和 <密码> 替换为 SelectDB 实例的数据库账号和密码。
通过 Claude Code 对话框发送以下指令，验证连接是否成功：
```
请检查 SelectDB 服务连接状态
```
check_service_health 工具并返回连接状态信息。
验证通过后，可通过自然语言指令查询和分析 SelectDB 中的数据。

Cursor

在项目根目录下创建 .cursor/mcp.json 文件。

写入以下配置内容：

{
  "mcpServers": {
    "selectdb": {
      "url": "<MCP服务地址>",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer <用户名>:<密码>"
      }
    }
  }
}

<MCP服务地址> 替换为控制台显示的 MCP 服务地址，<用户名> 和 <密码> 替换为 SelectDB 实例的数据库账号和密码。

保存文件并重启 Cursor，即可使用 SelectDB MCP 工具。可通过发送自然语言查询指令验证连接是否正常。

MCP Tool 一览

MCP Server 提供 10 个内置工具，分为三类：启动与健康检查、语义层查询、元数据与裸 SQL。

启动与健康检查

工具	说明
`get_query_guide`	返回完整工作流指引，包括何时使用语义层或裸 SQL、工具调用顺序和查询语法。建议在每次对话开始时调用。
`check_service_health`	返回 SelectDB 连通性及每个工作空间的状态（healthy / no_models / not_ready）和指标数量。

语义层查询

工具	说明
`list_metrics`	列出工作空间中所有可用指标（名称和描述）。必填参数：`workspace`。
`list_dimensions_for_metric`	返回指定指标的可用分组维度（名称、类型和描述），确保 `group_by` 参数不报错。必填参数：`workspace`、`metric_name`。
`query_metric`	核心查询工具。编译并执行语义查询，支持 `group_by`、`where`、`order_by`、`having`、`limit` 等参数。必填参数：`workspace`、`metrics`。
`reload_semantic_layer`	手动触发语义层重载。管理员修改 YAML 模型并提交后，如需立即生效可调用，否则系统每 60 秒自动轮询。

元数据与裸 SQL

仅在以下两种场景使用：语义层不可用（所有工作空间非 healthy），或语义层中无匹配指标。

工具	说明
`list_databases`	列出所有数据库。
`list_tables`	列出指定数据库中的表名。必填参数：`database`。
`describe_table`	查看物理表结构（列名、类型）。必填参数：`database`、`table`。
`execute_query`	执行裸 SQL 查询，仅允许只读语句（SELECT / SHOW / DESCRIBE / EXPLAIN）。必填参数：`sql`。

AI Agent 推荐工作流

AI Agent 每次对话的标准流程如下：

调用 get_query_guide 获取完整工作流指引。
调用 check_service_health 确认 SelectDB 连通，查看可用工作空间。
路由判断：
- 涉及聚合计算（求和、计数、比率、排名、趋势）→ 走语义层查询（步骤 4~6）。
- 涉及查看表结构或数据库列表 → 走元数据工具。
- 语义层不可用（所有工作空间非 healthy）→ 跳过语义层，直接使用元数据和裸 SQL。
调用 list_metrics 列出指标，匹配用户意图。
调用 list_dimensions_for_metric 获取可用分组维度。
调用 query_metric 执行查询。

重要

语义层可用且有匹配指标时，不得绕过 query_metric 直接使用 execute_query 编写 SQL。

使用 CLI 命令行工具

SelectDB 提供命令行客户端 doris-mcp-client，用于调用 MCP 工具和管理语义模型。

配置连接

通过环境变量或配置文件设置连接信息。

方式一：环境变量

export DORIS_MCP_SERVER=http://<MCP服务地址>:<端口>
export DORIS_MCP_TOKEN=<用户名>:<密码>

方式二：配置文件

创建 doris-mcp-client.toml 文件：

[server]
DORIS_MCP_SERVER = "http://<MCP服务地址>:<端口>"
DORIS_MCP_TOKEN = "<用户名>:<密码>"

调用 MCP 工具

# 列出所有可用工具
doris-mcp-client tool list

# 调用工具：JSON 参数
doris-mcp-client tool call query_metric --json \
  '{"workspace":"example","metrics":["total_amount"],"group_by":["channel"]}'

# 查看服务健康状态
doris-mcp-client tool call check_service_health

管理语义模型

# 列出工作空间的所有语义文件
doris-mcp-client semantic list -w example

# 上传 YAML 模型到暂存区
doris-mcp-client semantic push ./models -w example

# 拉取当前生效的语义模型到本地
doris-mcp-client semantic pull -o ./backup -w example

# 触发语义层重载
doris-mcp-client semantic reload -w example

# 查看语义层状态
doris-mcp-client semantic status

查询示例

探索数据结构

您：列出所有数据库
AI：[调用 list_databases]
    dw

您：查看 dw 库下有哪些表
AI：[调用 list_tables]
    orders, users, products, dim_date

您：查看 orders 表结构
AI：[调用 describe_table]
    列名        类型      注释
    order_id    BIGINT    订单ID
    user_id     BIGINT    用户ID
    amount      DECIMAL   金额
    channel     VARCHAR   渠道
    status      VARCHAR   状态
    order_date  DATE      下单日期

语义层查询

您：列出所有可用指标
AI：[调用 list_metrics]
    total_amount      订单总金额
    order_count       订单数
    avg_amount        平均客单价
    unique_users      下单用户数

您：查询最近 7 天各渠道的订单总金额
AI：[调用 list_dimensions_for_metric] → channel
    [调用 query_metric]
    渠道      总金额
    线上      12345.00
    线下      15678.00

常见问题

连接报 401 错误

确认 Token 格式正确：<用户名>:<密码>（英文冒号分隔）。

语义查询报错 workspace not found

确认工作空间名称正确，默认可用 example。登录 WebUI 查看可用工作空间。

能否执行写操作

不能。execute_query 仅允许只读 SQL（SELECT / SHOW / DESCRIBE / EXPLAIN）。

查询很慢

数据量大时，在查询中添加 LIMIT 或缩小时间范围。

语义层能用哪些指标

通过 CLI 查看可用指标和工作空间状态：

doris-mcp-client tool call list_metrics --json '{"workspace":"example"}'
doris-mcp-client tool call check_service_health