Skip to main content

QuickStart with MCP

Overview​

The Wren Engine MCP Server implements the Model Context Protocol (MCP) specification to enable AI agents to interact with Wren Engine for data querying and analysis capabilities.

Prerequisites​

uv A fast Python package manager and virtual environment tool

If you haven't installed uv on your computer yet, you can just run:

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

Setup Guide​

Step 1: Clone the Repository​

Start by cloning the Wren Engine repository from GitHub:

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

Step 2: Configure Environment Variables​

The server requires the following environment variables:

VariableDescription
WREN_URLURL of the Wren Ibis server
CONNECTION_INFO_FILEPath to the connection info file for your data source
MDL_PATHPath to the Model Definition Language (MDL) file

You can set these variables directly in your environment or use an .env file

For example, your .env file might look like this in the project root of mcp-server.

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

Step 3: Prepare Your Connection Info File and MDL File​

Create a JSON file with the connection information for your data source. Let's use the local parquet file as the example. You can refer to the ConnectionInfo documentation for other data sources. Example for the local parquet file:

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

Example for 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"
        }
    ]
  }

Step 4: Set Up Python Environment​

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

# Verify the setup
uv run app/wren.py

You should see confirmation that the MDL and connection info are loaded. Press Ctrl+C to terminate the process.

Step 5: Start Wren Engine​

Option A: If you already have Wren Engine running, ensure your WREN_URL points to it.

Option B: Start Wren Engine using Docker:

cd docker
docker compose up

You can check the full Compose file in the installation documentation

Step 6: Configure the MCP Server​

Create a configuration file for your AI agent with this structure:

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

Configuration Notes:

  • You may need to use the full path to the uv executable (find it with which uv on MacOS/Linux or where uv on Windows)
  • The directory path must be absolute
  • More information is available in the MCP Server Guide

Step 7: Connect Your AI Agent​

The following AI agents support Wren MCP Server:

Follow their respective guides to deploy the MCP configuration.

Step 8: Verify the Connection​

Ask your AI agent (Cline) to perform a health check for the Wren Engine connection. Here We use Cline for demo

health

Step 9: Start Using Wren through Your AI Agent​

Example 1: List available table

list table

Ecample 2: Which customers have spent the most in total orders, and what is their average order value? top five customer

Troubleshooting​

  • If the server fails to start, check that all environment variables are set correctly
  • Ensure your connection info file contains the correct credentials and includes the required dataSource field
  • Verify that the Wren Engine is running and accessible at the URL specified in WREN_URL

Additional Resources​