ODPS MCP 服务器

用于阿里云 MaxCompute 的只读 MCP 服务器。

ASGI 模式

使用 create_app() 启动 HTTP 服务器。该应用公开 GET /health，将标准 MCP Streamable HTTP 应用挂载到 /mcp，并保留 / 作为旧版调用者的兼容路径。

示例：

uvicorn odps_mcp_server.server:create_app --factory

端点：

• 标准 MCP 端点：http://<host>:<port>/mcp

• 兼容 MCP 端点：http://<host>:<port>/

• 健康检查：http://<host>:<port>/health

此服务通过 streamable-http 公开远程 MCP 端点，以便内部代理能够安全地查询已加入白名单的 MaxCompute 表。

环境

在运行服务器之前，请设置以下环境变量：

• ALIBABA_CLOUD_ACCESS_KEY_ID

• ALIBABA_CLOUD_ACCESS_KEY_SECRET

• ODPS_ENDPOINT

• ODPS_PROJECT

• ODPS_ALLOWLIST_PATH

ODPS_ALLOWLIST_PATH 应指向您的策略文件。请从 config/allowlist.example.yaml 开始，并将示例项目和表名替换为您批准的白名单内容。

如果您需要本地一键启动流程，请将 .env.local.example 复制为 .env.local 并填入您的 ODPS 凭据。该文件已被 git 忽略。

本地设置

在虚拟环境中安装依赖项：

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

如果您更喜欢使用 uv，等效流程为：

uv venv
uv pip install -e .

策略文件

白名单文件控制 MCP 服务器可以访问哪些 MaxCompute 项目和表。示例：

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

default_limit: 100
max_limit: 200

运行 MCP 服务器

使用以下命令运行服务器：

python -m odps_mcp_server.server

服务器配置为以 streamable-http 模式启动 MCP 传输。

对于 Windows 上的本地开发，您也可以使用：

.\scripts\start-local-mcp.ps1

如果您更喜欢由 .env.local 支持的一键启动流程，请使用：

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

内部代理集成

您的内部代理应连接到标准 MCP 端点 http://<host>:<port>/mcp。根路径 / 仅保留用于向后兼容。该服务公开了以下工具：

• list_allowed_tables

• describe_table

• preview_table

• run_select_sql

推荐的代理流程：

1. 列出允许的表。

2. 读取所选表的架构。

3. 必要时预览行数据。

4. 针对白名单表运行过滤后的 SELECT 查询。

手动冒烟测试

使用 scripts/manual_smoke_test.py 验证针对非生产 MaxCompute 项目的连接性和策略行为。

示例：

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"

在审核白名单和行限制之前，请勿将冒烟测试指向仅限生产的项目。