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:
- MacOS/Linux
- Windows
curl -LsSf https://astral.sh/uv/install.sh | sh
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
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:
Variable | Description |
---|---|
WREN_URL | URL of the Wren Ibis server |
CONNECTION_INFO_FILE | Path to the connection info file for your data source |
MDL_PATH | Path 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 details for your data source. Example for 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 withwhich uv
on MacOS/Linux orwhere 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
Step 9: Start Using Wren through Your AI Agent
Example 1: List available table
Ecample 2: Which customers have spent the most in total orders, and what is their average order value?
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