MCP概述与接入-云原生大数据计算服务 MaxCompute(MaxCompute)-阿里云帮助中心

MaxCompute MCP Server（MCMCP）基于MCP（Model Context Protocol）协议，将MaxCompute底层的元数据、计算和存储服务封装为Agent可理解、可执行的统一能力接入层。通过MCMCP，AI Agent可以直接完成大规模数据分析、多模数据加工处理和智能化运维。

功能概述

Agent通过标准MCP协议直接调用MCMCP提供的结构化工具，无需额外的SDK或驱动。MCMCP覆盖从元数据浏览、SQL分析到表管理的完整数据操作链路。

核心能力

Catalog元数据浏览与搜索：按项目、Schema、表、字段、分区层级浏览，支持自然语言搜索。
表管理与元数据维护：创建表（支持生命周期、主键、部分列更新等选项）、插入少量数据、更新表注释/标签/列描述。
身份与权限检查：当前账号身份、SHOW GRANTS权限信息。
多种认证方式：AK/SK、STS、Credentials URI、ECS RAM Role及默认凭证链。
只读SQL分析：成本预估、异步执行、实例状态查询、结果读取。服务端强制只读保护。

架构概览

MCMCP采用分层架构设计，从上到下分为以下层级：

用户Agent生态：支持OpenClaw、DataWorks Agent、Qwen Code、QoderWork、MaxAgent等多种Agent客户端接入。
MaxCompute Skills集合：Agent通用技能包，包含语义包、常用命令、开发模板、使用限制等。通过MaxCompute OpenAPI、InfraAgent、CatalogAI扩展Agent能力。
MCMCP服务：把MaxCompute OpenAPI / StorageAPI / CatalogAPI封装成可被Agent直接调用的结构化工具。
MaxCompute底层能力：
- Metadata（元数据）：
  Catalog / Schema / Table / Partition。能力包括授权、审计、数据发现、数据导出、脱敏、行级权限、数据共享。
- Compute Engines（计算引擎）：
  MaxCompute SQL、MaxFrame、MC Spark。算力类型包括异构算力CU/GU、AI Function、模型。
- Storage（存储）：
  Table（Append / PK Delta Table）；数据类型Blob / JSON / ARRAY / MAP / STRUCT。能力包括冷热分层、多副本、多AZ容灾、回收站/Time Travel、数据快照、存储加密。

前置条件

Python
- 3.10及更高版本。
- 推荐使用包管理工具uv，用于安装依赖和运行服务。
阿里云凭证
AK/SK、STS、凭证服务 URI、ECS RAM Role 或阿里云默认凭证链。
MaxCompute
- 项目：至少有一个可访问的MaxCompute项目。并确认默认项目名，用于创建ODPS client、SQL提交、权限检查和省略项目参数时的默认上下文。
- 确认endpoint，例如https://service.cn-hangzhou.maxcompute.aliyun.com/api。
确认主账号UID，即namespaceId。

注意事项

不要提交 config.json、AK/SK、STS token、凭证 URI、查询结果文件或覆盖率输出。
生产环境优先使用动态凭证来源，如 ALIBABA_CLOUD_CREDENTIALS_URI 或 RAM Role。
为 MCP 使用的身份配置最小必要权限，不要直接使用高权限主账号 AK。
execute_sql 有只读保护，但 create_table、insert_values、update_table 会修改资源或元数据。
output_uri 只允许写服务端本地文件，应使用专门的安全目录，避免写入系统敏感路径。
对成本高、结果大或跨项目的查询，先预估成本并确认项目、Schema、表名引用无误。

如遇问题，请联系 MaxCompute 团队或在GitHub仓库提交Issue。

下载与安装

下载MCMCP

GitHub Repo：https://github.com/aliyun/alibabacloud-maxcompute-mcp-server

适用于Claude Code / OpenCode / Qoder / Cursor 等MCP客户端。

通过源码安装

终端输入：

git clone https://github.com/aliyun/alibabacloud-maxcompute-mcp-server.git
cd alibabacloud-maxcompute-mcp-server
uv sync

验证 CLI 入口：

uv run alibabacloud-maxcompute-mcp-server --help

复制配置模板：
```
cp config.example.json config.json
```
警告
config.json包含敏感信息（AK/SK等），必须只保存在本地，不要提交到Git。
编辑 config.json 后，可先在命令行启动一次服务确认没有配置错误：
```
uv run alibabacloud-maxcompute-mcp-server --config config.json
```

默认传输方式是 stdio，正常启动后会等待 MCP 客户端通过标准输入输出通信。

配置MaxCompute连接

MCMCP支持两种配置来源：

配置文件：通过--config /path/to/config.json或环境变量MAXCOMPUTE_CATALOG_CONFIG指定。
环境变量：可覆盖配置文件，也可以完全不使用配置文件。

配置文件方式

警告

config.json包含敏感信息（AK/SK等），必须只保存在本地，不要提交到Git。

config.json示例：

{
  "maxcompute": {
    "maxcompute_endpoint": "https://service.cn-hangzhou.maxcompute.aliyun.com/api",
    "defaultProject": "<DEFAULT_PROJECT_NAME>",
    "namespaceId": "<ALIBABACLOUD_ACCOUNT_UID>",
    "accessKeyId": "<ALIBABA_CLOUD_ACCESS_KEY_ID>",
    "accessKeySecret": "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"
  }
}

点击查看字段说明

字段	是否必填	说明
`maxcompute_endpoint`	是	MaxCompute服务端点，按Region选择。
`defaultProject`	强烈建议	默认项目名。未配置时SQL、权限、实例和自动解析Catalog endpoint等能力不可用。
`namespaceId`	可选	主账号UID。仅`search_meta_data`元数据搜索需要。
`catalogapi_endpoint`	可选	Catalog API地址。未配置时通过 ODPS client 从 `maxcompute_endpoint` 自动解析，因此通常也需要 `defaultProject`
`protocol`	可选	https或http。默认按endpoint推导，通常无需设置。
`accessKeyId / accessKeySecret`	可选	静态AK/SK。适合开发调试，生产建议使用动态凭证。
`securityToken`	可选	STS token。与静态AK/SK一起使用。

环境变量方式

export MAXCOMPUTE_ENDPOINT="https://service.cn-hangzhou.maxcompute.aliyun.com/api"
export MAXCOMPUTE_DEFAULT_PROJECT="<DEFAULT_PROJECT_NAME>"
export MAXCOMPUTE_NAMESPACE_ID="<ALIBABACLOUD_ACCOUNT_UID>"

# 方式 1：AK/SK
export ALIBABA_CLOUD_ACCESS_KEY_ID="<ALIBABA_CLOUD_ACCESS_KEY_ID>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<ALIBABA_CLOUD_ACCESS_KEY_SECRET>"

# 方式 2：STS
export ALIBABA_CLOUD_ACCESS_KEY_ID="<STS_ACCESS_KEY_ID>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<STS_ACCESS_KEY_SECRET>"
export ALIBABA_CLOUD_SECURITY_TOKEN="<STS_TOKEN>"

# 方式 3：凭证服务 URI，适合生产或平台托管环境
export ALIBABA_CLOUD_CREDENTIALS_URI="http://localhost:8765/credentials"

凭证解析规则：

如果环境变量或配置文件中设置了 AK/SK，MCMCP 会使用这组静态凭证。
如果没有设置静态 AK/SK，MCMCP 会使用阿里云 Credentials SDK 默认凭证链。
默认凭证链可使用 ALIBABA_CLOUD_CREDENTIALS_URI、本地阿里云配置、ECS RAM
Role、OIDC 等来源。
需要自动刷新 STS 时，优先使用凭证服务 URI、RAM Role 或其他动态凭证来源。

配置MCP客户端

Qoder / Cursor / Claude Code / 通用stdio客户端

常见客户端配置位置
客户端
配置位置
Cursor
~/.cursor/mcp.json
Claude Code
项目根目录.mcp.json
其他MCP客户端
参考对应客户端的MCP server配置说明

配置方式

使用配置文件

{
  "mcpServers": {
    "alibabacloud-maxcompute-mcp-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/alibabacloud-maxcompute-mcp-server", "run", "alibabacloud-maxcompute-mcp-server"],
      "env": {"MAXCOMPUTE_CATALOG_CONFIG": "/absolute/path/to/config.json"}
    }
  }
}

仅使用环境变量

{
  "mcpServers": {
    "alibabacloud-maxcompute-mcp-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/alibabacloud-maxcompute-mcp-server", "run", "alibabacloud-maxcompute-mcp-server"],
      "env": {
        "MAXCOMPUTE_ENDPOINT": "https://service.cn-hangzhou.maxcompute.aliyun.com/api",
        "MAXCOMPUTE_DEFAULT_PROJECT": "<DEFAULT_PROJECT_NAME>",
        "MAXCOMPUTE_NAMESPACE_ID": "<ALIBABACLOUD_ACCOUNT_UID>",
        "ALIBABA_CLOUD_ACCESS_KEY_ID": "<AK_ID>",
        "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "<AK_SECRET>"
      }
    }
  }
}

DataWorks个人实例 + Claude Code

DataWorks个人实例通常会注入ALIBABA_CLOUD_CREDENTIALS_URI。在这种环境中，config.json只需要包含endpoint、默认项目和可选的namespaceId：

{
  "maxcompute": {
    "maxcompute_endpoint": "https://service.cn-hangzhou.maxcompute.aliyun.com/api",
    "defaultProject": "<DEFAULT_PROJECT_NAME>",
    "namespaceId": "<ALIBABACLOUD_ACCOUNT_UID>"
  }
}

.mcp.json 示例：

{
  "mcpServers": {
    "alibabacloud-maxcompute-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/alibabacloud-maxcompute-mcp-server",
        "run",
        "alibabacloud-maxcompute-mcp-server"
      ],
      "env": {
        "MAXCOMPUTE_CATALOG_CONFIG": "/absolute/path/to/alibabacloud-maxcompute-mcp-server/config.json",
        "ALIBABA_CLOUD_CREDENTIALS_URI": "<VALUE_FROM_DATAWORKS_ENV>"
      }
    }
  }
}

可在实例内通过以下命令查看平台注入的凭证 URI：

echo "$ALIBABA_CLOUD_CREDENTIALS_URI"

Streamable HTTP模式

默认建议使用 stdio。需要远程或多进程接入时，可以启动 HTTP 模式：

uv run alibabacloud-maxcompute-mcp-server \
  --config /absolute/path/to/config.json \
  --transport http \
  --host 127.0.0.1 \
  --port 8000

客户端 MCP 地址填写：

http://127.0.0.1:8000/mcp

验证连接

配置完成后，重启 MCP 客户端，在对话中输入：

查看我的 MaxCompute 身份信息，不需要查询权限明细

Agent 应调用 check_access，并返回类似结构：

{
  "success": true,
  "data": {
    "identity": {
      "accessKeyId": "LTAI***xYzW",
      "defaultProject": "my_project",
      "endpoint": "https://service.cn-hangzhou.maxcompute.aliyun.com/api",
      "displayName": "user@example.com"
    }
  }
}

如需同时验证权限查询：

查看我在 my_project 项目中的 MaxCompute 权限

MCP工具一览

分类	工具	说明
Catalog元数据	`list_projects`	列出当前账号可访问的项目。
	`get_project`	获取项目详情，包括是否启用Schema。
	`list_schemas`	列出项目下的Schema。
	`get_schema`	获取Schema详情。
	`list_tables`	列出表、视图和外部表；返回namingModel区分二层/三层模型。
	`get_table_schema`	获取字段、分区键、表注释、标签、生命周期、sqlTableRef等信息。
	`get_partition_info`	获取分区表的分区列表、数据量和时间指标。
元数据搜索	`search_meta_data`	在配置的`namespaceId`下搜索表、资源、Schema。
SQL与实例	`cost_sql`	预估SQL成本，不执行SQL。
	`execute_sql`	执行只读SQL；默认异步返回instanceId。
	`get_instance_status`	查询实例状态、进度、LogView、资源消耗。
	`get_instance`	获取已完成实例的结果；支持通过`output_uri`将完整结果写入文件。
身份与权限	`check_access`	查询当前身份和当前用户在目标项目中的权限。
表管理	`create_table`	创建表，支持分区、生命周期、主键、存储层等参数。
表管理	`insert_values`	通过`INSERT INTO ... VALUES`插入少量数据。
表元数据维护	`update_table`	更新表注释、标签、生命周期、列注释、可空性和新增列。

关键约束

execute_sql 只允许只读 SQL。服务端会强制注入 odps.sql.read.only=true。
create_table、insert_values、update_table 是写入或元数据修改工具，需要谨慎授权。
查询 SQL 前建议先调用 get_table_schema，使用返回的 sqlTableRef 生成表引用。
list_tables 返回的 namingModel 会影响 SQL 表名格式：三层模型使用
schema.table 或 project.schema.table，二层模型使用 table 或 project.table。
search_meta_data 需要配置 namespaceId，查询语法通常需要包含 type=TABLE、
type=RESOURCE 或 type=SCHEMA。

常见使用场景

浏览项目和表

示例如下：

列出我能访问的 MaxCompute 项目，并查看 my_project 下有哪些 schema
查看 my_project 项目 default schema 下 user_info 表的字段、分区键和表注释

安全执行SQL查询

预估成本后再执行：

先查看 orders 表的结构，再预估这条 SQL 的成本：
SELECT COUNT(*) FROM orders WHERE dt='2026-05-01'

执行只读查询：

在 my_project 项目执行只读查询：
SELECT * FROM default.orders WHERE dt='2026-05-01' LIMIT 100

大查询建议让 Agent 走异步流程：

异步执行这个查询，返回 instanceId 后帮我轮询状态，完成后读取前 100 行结果

导出大结果

默认内联结果会受行数上限保护。需要完整结果时，使用output_uri：

同步执行这个查询，并把完整结果写到 file:///tmp/maxcompute-result/orders.jsonl；
响应里只需要给我预览和最终 outputPath

说明

output_uri写入的是MCP服务端所在机器的本地文件系统，不是客户端电脑。

检查身份和权限

查看当前 MCP 使用的 MaxCompute 身份，并列出我在 my_project 项目中的权限

搜索元数据

在 Catalog 中搜索名称包含 orders 的表，只看 my_project 项目

维护表业务元数据

先读取 default.orders 的当前表结构，然后把表注释改为“订单事实表”，
并把列 buyer_id 的注释改为“买家 ID”

update_table 支持的修改范围包括：

表注释：description
标签：labels
生命周期：expiration.days、expiration.partitionDays
列注释：columns.setComments
顶层列从非空改为可空：columns.setNullable
追加新列：columns.add

MaxCompute 不支持通过该工具删除列、修改列类型、重排列、在中间插入列、把可空列改为非空列，或修改嵌套列的可空性。

创建表和插入少量数据

在 my_project.default 下创建一张测试表 demo_user，
字段包括 id BIGINT、name STRING、dt STRING 分区字段，生命周期 7 天

向 demo_user 插入两行测试数据，dt 分区值为 2026-05-18

这类操作会修改MaxCompute资源，建议只授予测试项目或受控项目权限。

故障排查

MCP客户端看不到工具

检查项如下：

command 是否为 uv，args 中的 --directory 是否指向仓库绝对路径。
如果客户端找不到 uv，将 command 改成 which uv 返回的绝对路径。
仓库中是否已执行 uv sync。
MAXCOMPUTE_CATALOG_CONFIG 是否指向正确的 config.json。
是否重启了 Cursor、Claude Code 或对应 MCP 客户端。
在仓库目录手动运行 uv run alibabacloud-maxcompute-mcp-server --help 是否成功。

认证失败或连接失败

检查项如下：

MAXCOMPUTE_ENDPOINT 或 maxcompute_endpoint 是否与项目 Region 匹配。
AK/SK 或 STS token 是否有效且未过期。
使用凭证服务时，ALIBABA_CLOUD_CREDENTIALS_URI 是否能在 MCP 服务端机器访问。
是否给当前身份授予了目标项目的访问权限。
先用 check_access 验证当前身份，再排查具体工具。

`search_meta_data` 返回错误

常见原因：

未配置 namespaceId 或 MAXCOMPUTE_NAMESPACE_ID。
查询语句缺少 type=TABLE、type=RESOURCE 或 type=SCHEMA。
同时使用了不兼容的 project 和 region 条件。

SQL 表名解析失败

先调用 get_table_schema，让 Agent 使用返回的 sqlTableRef。

三层模型项目常见表名格式是 schema.table 或 project.schema.table；
二层模型项目常见表名格式是 table 或 project.table。

SQL 执行超时或结果被截断

默认推荐异步执行，拿到 instanceId 后通过 get_instance_status 和
get_instance 获取结果。
同步执行可设置 timeout，超时后仍可用返回的 instanceId 继续查询。
大结果使用 output_uri=file:///path/to/result.jsonl 写入服务端本地文件。
执行前可调用 cost_sql，再用 maxCU 限制资源消耗。

Information Schema语义包Skill使用手册

Information_Schema 是系统级运维（Ops）语义包，基于 MaxCompute 租户级的 INFORMATION_SCHEMA 元数据视图构建。它旨在为数据团队提供全方位的项目审计、用量分析与运维观测能力，将复杂的底层元数据转化为可自然语言查询的指标和实体。

Skill Repo：https://skills.aliyun.com/skills/alibabacloud-odps-information-schema

应用场景

存储压力诊断

能力：盘点存储TOP表，识别分区膨胀风险及数据滞后（新鲜度）问题。
Prompt举例："分析当前租户中占用存储最大的前10张表"、"检查哪些表存在分区膨胀风险"。

成本压力诊断

能力：拆解任务成本（按Owner/项目/类型），统计CU时消耗并定位高耗资源任务。
Prompt举例："最近一周计算成本最高的任务有哪些"、"统计各用户的资源消耗排行"。

任务失败激增分析

能力：监控失败率趋势，按维度（类型/Owner/项目）下钻分析失败根因。
Prompt举例："最近24小时内失败的任务有哪些"、"统计各类型任务的失败率"。

权限暴露审计

能力：审计表级授权分布，识别高危管理员账号及过度授权风险。
Prompt举例："哪些用户拥有管理员权限"、"统计每个用户被授权的表数量"。

热点表观测

能力：基于访问频次识别热表，结合最后访问时间自动发现"僵尸表"。
Prompt举例："哪些表访问最频繁"、"识别最近90天未访问的僵尸表"。

元数据治理缺口分析

能力：统计表/字段注释覆盖率，定位元数据缺失及数据滞后的治理薄弱点。
Prompt举例："统计列注释覆盖率"、"找出没有表注释的表"。

作业性能分析

能力：分析任务平均/P99执行时长，识别长尾慢任务及排队等待异常。
Prompt举例："查看P99最慢任务"、"最近一周任务平均执行时长是多少"。

数据通道审计

能力：统计Tunnel上传下载量，溯源公网下载IP并检测异常传输行为。
Prompt举例："查看最近24小时的Tunnel上传下载数据量"、"审计公网下载来源IP"。

用户角色审计

能力：梳理用户-角色映射关系，审查管理角色分配合理性及非活跃高权账号。
Prompt举例："列出所有admin和super_administrator用户"、"查看用户角色分配情况"。

分区生命周期分析

能力：监控分区数量增长趋势，检查生命周期策略生效情况及过期分区清理状态。
Prompt举例："哪些表的分区数量超过500"、"检查生命周期未启用的分区表"。

Quota资源监控

能力：实时监控CPU/内存配额使用率，预警资源瓶颈与分配不均。
Prompt举例："查看当前所有Quota的CPU使用率"、"哪些Quota的资源使用率超过阈值"。

客户端	配置位置
Cursor	`~/.cursor/mcp.json`
Claude Code	项目根目录`.mcp.json`
其他MCP客户端	参考对应客户端的MCP server配置说明