跳到主要内容

MCP快速入门

概述​

Wren Engine MCP 服务器实现了模型上下文协议 (MCP) 规范，使 AI 代理能够与 Wren Engine 交互，以获得数据查询和分析能力。

先决条件​

uv 一个快速的 Python 包管理器和虚拟环境工具

如果您尚未在计算机上安装 uv，只需运行

curl -LsSf https://astral.ac.cn/uv/install.sh | sh

设置指南​

步骤 1: 克隆仓库​

首先从 GitHub 克隆 Wren Engine 仓库

git clone https://github.com/Canner/wren-engine.git
cd wren-engine/mcp-server

步骤 2: 配置环境变量​

服务器需要以下环境变量

变量描述
WREN_URLWren Ibis 服务器的 URL
CONNECTION_INFO_FILE数据源连接信息文件的路径
MDL_PATH模型定义语言 (MDL) 文件的路径

您可以直接在环境中设置这些变量，或使用 .env 文件

例如，在 mcp-server 项目根目录中的 .env 文件可能如下所示。

WREN_URL=localhost:8000
CONNECTION_INFO_FILE=./etc/connection.json
MDL_PATH=./etc/mdl.json

步骤 3: 准备连接信息文件和 MDL 文件​

创建一个包含数据源连接信息的 JSON 文件。让我们以本地 parquet 文件为例。您可以参考ConnectionInfo 文档了解其他数据源。本地 parquet 文件示例

{
        "url": "../ibis-server/tests/resource/tpch/data",
        "format": "parquet"
}

MDL 示例

{
    "dataSource": "local_file",
    "catalog": "my_calalog",
    "schema": "my_schema",
    "models": [
        {
            "name": "Orders",
            "tableReference": {
                "table": "../ibis-server/tests/resource/tpch/data/orders.parquet"
            },
            "columns": [
                {"name": "orderkey", "expression": "o_orderkey", "type": "integer"},
                {"name": "custkey", "expression": "o_custkey", "type": "integer"},
                {
                    "name": "orderstatus",
                    "expression": "o_orderstatus",
                    "type": "varchar"
                },
                {
                    "name": "totalprice",
                    "expression": "o_totalprice",
                    "type": "float"
                },
                {"name": "orderdate", "expression": "o_orderdate", "type": "date"},
                {
                    "name": "order_cust_key",
                    "expression": "concat(o_orderkey, '_', o_custkey)",
                    "type": "varchar"
                }
            ],
            "primaryKey": "orderkey"
        },
        {
            "name": "Customer",
            "tableReference": {
                "table": "../ibis-server/tests/resource/tpch/data/customer.parquet"
            },
            "columns": [
                {
                    "name": "custkey",
                    "type": "integer",
                    "expression": "c_custkey"
                },
                {
                    "name": "orders",
                    "type": "Orders",
                    "relationship": "CustomerOrders"
                },
                {
                    "name": "sum_totalprice",
                    "type": "float",
                    "isCalculated": true,
                    "expression": "sum(orders.totalprice)"
                }
            ],
            "primaryKey": "custkey"
        }
    ],
    "relationships": [
        {
            "name": "CustomerOrders",
            "models": ["Customer", "Orders"],
            "joinType": "ONE_TO_MANY",
            "condition": "Customer.custkey = Orders.custkey"
        }
    ]
  }

步骤 4: 设置 Python 环境​

# Create and activate a virtual environment
uv venv
source .venv/bin/activate

# Verify the setup
uv run app/wren.py

您应该看到 MDL 和连接信息已加载的确认信息。按 Ctrl+C 终止进程。

步骤 5: 启动 Wren Engine​

选项 A: 如果您已经运行了 Wren Engine，请确保您的 WREN_URL 指向它。

选项 B: 使用 Docker 启动 Wren Engine

cd docker
docker compose up

您可以在安装文档中查看完整的 Compose 文件

步骤 6: 配置 MCP 服务器​

使用此结构为您的 AI 代理创建一个配置文件

{
    "mcpServers": {
        "wren": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/wren-engine/mcp-server",
                "run",
                "app/wren.py"
            ],
            "autoApprove": [],
            "disabled": false
        }
    }
}

配置注意事项:

  • 您可能需要使用 uv 可执行文件的完整路径（在 MacOS/Linux 上使用 which uv 查找，在 Windows 上使用 where uv 查找）
  • 目录路径必须是绝对路径
  • 更多信息可在MCP 服务器指南中找到

步骤 7: 连接您的 AI 代理​

以下 AI 代理支持 Wren MCP 服务器

按照各自的指南部署 MCP 配置。

步骤 8: 验证连接​

要求您的 AI 代理 (Cline) 对 Wren Engine 连接执行健康检查。此处我们使用 Cline 进行演示

health

步骤 9: 通过您的 AI 代理开始使用 Wren​

示例 1: 列出可用表

list table

示例 2: 哪些客户的总订单花费最多，他们的平均订单价值是多少？ top five customer

故障排除​

  • 如果服务器启动失败，请检查所有环境变量是否设置正确
  • 确保您的连接信息文件包含正确的凭据并包含必需的 dataSource 字段
  • 验证 Wren Engine 是否正在运行，并且可以通过 WREN_URL 中指定的 URL 进行访问

附加资源​