ODPS MCP Server

Read-only MCP server for Alibaba Cloud MaxCompute.

ASGI Mode

Use create_app() for the HTTP server. The app exposes GET /health, mounts the standard MCP Streamable HTTP app at /mcp, and keeps / as a compatibility path for older callers.

Example:

uvicorn odps_mcp_server.server:create_app --factory

Endpoints:

• Standard MCP endpoint: http://<host>:<port>/mcp

• Compatibility MCP endpoint: http://<host>:<port>/

• Health check: http://<host>:<port>/health

This service exposes a remote MCP endpoint over streamable-http so an internal agent can query allowlisted MaxCompute tables safely.

Environment

Set these environment variables before running the server:

• ALIBABA_CLOUD_ACCESS_KEY_ID

• ALIBABA_CLOUD_ACCESS_KEY_SECRET

• ODPS_ENDPOINT

• ODPS_PROJECT

• ODPS_ALLOWLIST_PATH

ODPS_ALLOWLIST_PATH should point to your policy file. Start with config/allowlist.example.yaml and replace the sample project and table names with your approved allowlist.

If you want a local one-click startup flow, copy .env.local.example to .env.local and fill in your ODPS credentials. The file is ignored by git.

Local Setup

Install dependencies in a virtual environment:

python -m venv .venv
.venv\Scripts\activate
pip install -e .

If you prefer uv, the equivalent flow is:

uv venv
uv pip install -e .

Policy File

The allowlist file controls which MaxCompute projects and tables the MCP server can access. Example:

projects:
  analytics:
    tables:
      sales_orders:
        allowed_columns:
          - order_id
          - order_date

default_limit: 100
max_limit: 200

Run The MCP Server

Run the server with:

python -m odps_mcp_server.server

The server is configured to start the MCP transport in streamable-http mode.

For local development on Windows, you can also use:

.\scripts\start-local-mcp.ps1

If you prefer a one-click startup flow backed by .env.local, use:

.\scripts\start-local-mcp-oneclick.ps1

Internal Agent Integration

Your internal agent should connect to the standard MCP endpoint http://<host>:<port>/mcp. The root path / remains available only for backwards compatibility. The service exposes these tools:

• list_allowed_tables

• describe_table

• preview_table

• run_select_sql

Recommended agent flow:

1. List allowed tables.

2. Read the schema for a chosen table.

3. Preview rows if needed.

4. Run a filtered SELECT query against the allowlisted table.

Manual Smoke Test

Use scripts/manual_smoke_test.py to validate connectivity and policy behavior against a non-production MaxCompute project.

Examples:

python scripts/manual_smoke_test.py list-tables --project analytics
python scripts/manual_smoke_test.py describe-table --project analytics --table sales_orders
python scripts/manual_smoke_test.py run-sql --project analytics --sql "SELECT order_id FROM analytics.sales_orders LIMIT 10"

Do not point the smoke test at a production-only project until the allowlist and row limits are reviewed.