Skip to content

README.md

Latest commit

 

History

History
245 lines (173 loc) · 8.58 KB

README.md

File metadata and controls

245 lines (173 loc) · 8.58 KB

Wren MCP Server

The Wren MCP Server is a Model Context Protocol (MCP) server that provides tools for interacting with Wren Engine to facilitate AI agent integration.

Requirements

Before setting up the Wren MCP Server, ensure you have the following dependency installed:

  • uv - A fast and efficient Python package manager.

Web UI

When the MCP server starts, a configuration Web UI is available at http://localhost:9001 (port controlled by WEB_UI_PORT).

Read-only Mode

The top card in the UI is a Read-only Mode toggle. When enabled:

  • The AI agent cannot call deploy, deploy_manifest, list_remote_tables, or list_remote_constraints — those tools return an error immediately.
  • All read-only tools (query, dry_run, get_manifest, metadata tools, etc.) continue to work normally.
  • The toggle state is persisted to ~/.wren/mcp-ui-settings.json and restored on the next server startup.

Use read-only mode to allow an AI agent to query your data without being able to modify the deployed MDL or discover the raw database schema.

MDL Status

Shows whether an MDL is currently deployed, the number of models and columns, and the active data source.

Connection Info

Select the data source type and fill in connection credentials. Clicking Save Connection tests the connection against ibis-server and persists the credentials to CONNECTION_INFO_FILE.

MDL Editor

A Monaco JSON editor showing the currently deployed MDL manifest. Edit inline and click Save & Deploy to update the live MDL.

Environment Variables

The server requires the following environment variables to be set:

Variable Default Description
WREN_URL localhost:8000 The URL of the Wren Ibis server.
CONNECTION_INFO_FILE ~/.wren/connection_info.json Path to the connection info file.
MDL_PATH — Path to the MDL JSON file.
WEB_UI_PORT 9001 Port for the configuration Web UI.
WEB_UI_ENABLED true Set to false to disable the Web UI entirely.
SETTINGS_FILE ~/.wren/mcp-ui-settings.json Path to the persisted UI settings file (read-only mode, etc.).

Connection Info

The following JSON is a connection info of a Postgres. You can find the requried fields for each data source in the source code.

{
    "host": "localhost",
    "port": "5432",
    "user": "test",
    "password": "test",
    "database": "test"
}

The dataSource field is requried.

In the MDL, the dataSource field is required to indicate which data source should be connected.

.env File Support

Wren MCP Server supports an .env file for easier environment configuration. You can define all the required environment variables in this file.

Installation & Usage

1. Set the Python Envrionment

Use the uv command to create a virtual envrionment and activate it:

> uv venv
Using CPython 3.11.11
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
> source .venv/bin/activate   
> uv run app/wren.py
Loaded MDL etc/mdl.json
Loaded connection info etc/pg_conneciton.json

You would see that the MDL and connection info are loaded. Then, you can use Ctrl + C terminate the process.

2. Start Wren Engine and Ibis Server

  • If you already have a running Wren Engine, ensure that WREN_URL is correctly set to point to your server.

  • If you don't have a running engine, you can start one using Docker:

    cd docker
docker compose up

MDL Workspace

The workspace/ directory is the conventional location for MDL files when using Docker. It is mounted into the container at /workspace.

Input — load an existing MDL: Place your MDL JSON file in mcp-server/workspace/ on your host, then reference it in the MCP tool:

deploy(mdl_file_path="/workspace/my_mdl.json")

Output — save a generated MDL: The agent writes YAML project files and compiled MDL JSON back to your host via the wren-project skill:

# agent writes: mcp-server/workspace/my_project/wren_project.yml, models/*.yml, ...
# agent compiles to: mcp-server/workspace/my_project/target/mdl.json

Custom host path: Set MDL_WORKSPACE in docker/.env to point to any directory on your host:

# docker/.env
MDL_WORKSPACE=/Users/me/my-mdl-files

3. Set Environment Variables

There are two ways to set the required environment variables:

  • Set up .env file in the root directory of the MCP server. Make sure all required environment variables are properly configured, either in your system or within a .env file.
  • Set up system environment variables in MCP configuration. See the next step.

4. Configure the MCP Server

Create a configuration file with the following structure:

{
    "mcpServers": {
        "wren": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/wren-engine/mcp-server",
                "run",
                "app/wren.py"
            ],
            "env": {
                "WREN_URL": "localhost:8000",
                "CONNECTION_INFO_FILE": "/path-to-connection-info/connection.json",
                "MDL_PATH": "/path-to-mdl/mdl.json"
            },
            "autoApprove": [],
            "disabled": false
        }
    }
}

Notes:

  • You may need to provide the full path to the uv executable in the "command" field. You can find it using:
    • MacOS/Linux: which uv
    • Windows: where uv
  • Ensure that the absolute path to the MCP server directory is used in the configuration.
  • For more details, refer to the MCP Server Guide.

5. Choose an AI Agent That Supports MCP Server

The following AI agents are compatible with Wren MCP Server and deploy the MCP config:

6. Check the Wren Engine is Connected

You can ask the AI agent to perform a health check for Wren Engine.

7. Start the Conversation

Now, you can start asking questions through your AI agent and interact with Wren Engine. Tip: prime your agent with a short instruction so it knows how to use the Wren MCP tools.

Recommended prompt:

Use the get_wren_guide() tool to learn how to use Wren Engine and discover available tools and examples.

Optional follow-ups:

  • "Open the Wren guide."
  • "What Wren MCP tools are available?"
  • "Show me the available tables in Wren Engine."
  • "Query Wren Engine to get ... (your question here)."

Generating an MDL (No Database Drivers Required)

The wren-generate-mdl skill (skills/wren-generate-mdl/SKILL.md) guides any AI agent through creating a Wren MDL manifest from scratch — using ibis-server's metadata endpoints for schema discovery. No local database drivers need to be installed on the MCP server.

How it works

The agent calls MCP tools in sequence:

User  → "Generate an MDL for my PostgreSQL ecommerce database"

User  → (configures connection info via Web UI at http://localhost:9001)

Agent → health_check()
      ← "Wren Engine is reachable."

Agent → list_remote_tables()
      ← [{"name":"orders","columns":[...]}, {"name":"customers","columns":[...]}, ...]

Agent → list_remote_constraints()
      ← [{"constraintType":"FOREIGN_KEY","constraintTable":"orders", ...}]

Agent → (builds MDL JSON from schema info)

Agent → mdl_validate_manifest({"catalog":"wren","schema":"public",
           "dataSource":"POSTGRES","models":[...]})
      ← "MDL validation passed."

Agent → deploy_manifest({"catalog":"wren","schema":"public","dataSource":"POSTGRES","models":[...]})
      ← "MDL deployed successfully (5 models, 23 columns)"

Note: Connection info can only be configured through the Web UI — there is no MCP tool for setting credentials.

Environment Variables

Variable Required Description
WREN_ENGINE_ENDPOINT No ibis-server URL for dry-plan check in mdl_validate_manifest (default: http://localhost:8000)

Additional Resources