MaxCompute:Set up the local MCMCP Server

Core capabilities

• Catalog metadata browsing and search: Browse projects, schemas, tables, fields, and partitions hierarchically. Supports natural language search.

• Table management and metadata maintenance: Create tables (with options for lifecycle, primary key, and partial column updates), insert small amounts of data, and update table comments, tags, or column descriptions.

• Identity and permission checks: View current account identity and SHOW GRANTS permission details.

• Multiple authentication methods: AccessKey/SecretKey (AK/SK), Security Token Service (STS), Credentials URI, ECS RAM Role, and the default Alibaba Cloud credential chain.

• Read-only SQL analysis: Cost estimation, asynchronous execution, instance status queries, and result retrieval. Enforced as read-only on the server side.

Architecture overview

MCMCP uses a layered architecture, from top to bottom:

• User Agent ecosystem: Supports multiple Agent clients including OpenClaw, DataWorks Agent, Qwen Code, QoderWork, and MaxAgent.

• MaxCompute Skills collection: A universal skill package for Agents, containing semantic packs, common commands, development templates, and usage limits. Extends Agent capabilities via MaxCompute OpenAPI, InfraAgent, and CatalogAI.

• MCMCP service: Wraps MaxCompute OpenAPI, StorageAPI, and CatalogAPI into structured tools directly callable by Agents.

• MaxCompute core capabilities:

  • Metadata:

    Catalog / Schema / Table / Partition. Features include authorization, auditing, data discovery, data exporting, masking, row-level permissions, and data sharing.

  • Compute Engines:

    MaxCompute SQL, MaxFrame, MC Spark. Compute types include heterogeneous CU/GU, AI functions, and models.

  • Storage:

    Table (Append / PK Delta Table); data types include BLOB, JSON, ARRAY, MAP, STRUCT. Features include automatic storage tiering, multi-replica, multi-AZ disaster recovery, recycle bin/Time Travel, data snapshots, and storage encryption.

Download MCMCP

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

Compatible with MCP clients such as Claude Code, OpenCode, Qoder, and Cursor.

Install from source

1. In your terminal, run:

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

2. Verify the CLI entry point:

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

3. Copy the configuration template:

   cp config.example.json config.json

   Warning

   config.json contains sensitive information (such as AK/SK). Keep it local only—do not commit it to Git.

4. After editing config.json, start the service once from the command line to confirm there are no configuration errors:

   uv run alibabacloud-maxcompute-mcp-server --config config.json

The default transport method is stdio. After successful startup, the server waits for communication from the MCP client via standard input and output.

Browse projects and tables

Example:

List MaxCompute projects I can access, then show schemas in my_project
Show fields, partition keys, and table comments for user_info in my_project's default schema

Run SQL queries securely

Estimate cost before execution:

First show the structure of the orders table, then estimate the cost of this SQL:
SELECT COUNT(*) FROM orders WHERE dt='2026-05-01'

Run a read-only query:

Run this read-only query in my_project:
SELECT * FROM default.orders WHERE dt='2026-05-01' LIMIT 100

For large queries, use asynchronous execution:

Run this query asynchronously. After returning the instanceId, poll its status and read the first 100 rows when done

Export large results

Inline results are capped by row limits. For full results, use output_uri:

Run this query synchronously and write the full result to file:///tmp/maxcompute-result/orders.jsonl;
Only show me a preview and the final outputPath in the response

Check identity and permissions

Show the MaxCompute identity used by MCP and list my permissions in my_project

Search metadata

Search the Catalog for tables with names containing 'orders', limited to my_project

Maintain business metadata

First read the current schema of default.orders, then update the table comment to 'Order fact table'
and change the buyer_id column comment to 'Buyer ID'

update_table supports these changes:

• Table comment: description

• Tags: labels

• Lifecycle: expiration.days, expiration.partitionDays

• Column comments: columns.setComments

• Change top-level columns from non-nullable to nullable: columns.setNullable

• Add new columns: columns.add

MaxCompute does not support deleting columns, changing column types, reordering columns, inserting columns in the middle, changing nullable columns to non-nullable, or modifying nullability of nested columns via this tool.

Create tables and insert small data sets

Create a test table demo_user in my_project.default
with fields id BIGINT, name STRING, and dt STRING as a partition key, with a 7-day lifecycle

Insert two test rows into demo_user with dt partition value 2026-05-18

These operations modify MaxCompute resources. Grant permissions only for test or controlled projects.

MCP client does not show tools

Check the following:

1. Is command set to uv? Does args include --directory pointing to the absolute path of the repo?

2. If the client cannot find uv, replace command with the absolute path returned by which uv.

3. Have you run uv sync in the repo?

4. Does MAXCOMPUTE_CATALOG_CONFIG point to the correct config.json?

5. Did you restart Cursor, Claude Code, or your MCP client?

6. Does manually running uv run alibabacloud-maxcompute-mcp-server --help in the repo directory succeed?

Authentication or connection failures

Check the following:

1. Does MAXCOMPUTE_ENDPOINT or maxcompute_endpoint match your project’s region?

2. Are your AK/SK or STS token valid and not expired?

3. If using a credentials service, can ALIBABA_CLOUD_CREDENTIALS_URI be accessed from the MCP server machine?

4. Has the current identity been granted access to the target project?

5. First verify your identity with check_access, then troubleshoot specific tools.

search_meta_data returns an error

Common causes:

• namespaceId or MAXCOMPUTE_NAMESPACE_ID is not configured.

• The query lacks type=TABLE, type=RESOURCE, or type=SCHEMA.

• The query uses incompatible project and region conditions.

SQL table name resolution fails

First call get_table_schema and have the Agent use the returned sqlTableRef.

• Three-layer model tables commonly use schema.table or project.schema.table;

• Two-layer model tables commonly use table or project.table.

SQL execution times out or results are truncated

• We recommend asynchronous execution by default. After obtaining the instanceId, use get_instance_status and

  get_instance to retrieve the results.

• For synchronous execution, set a timeout. If it times out, you can still use the returned instanceId to continue querying.

• For large results, use output_uri=file:///path/to/result.jsonl to write to a local file on the server.

• Before execution, call cost_sql, then use maxCU to limit resource consumption.

Scenarios