semantic-warehouse-mcp

A read-only MCP server that lets any AI agent work with SQL databases the way an analyst does: knowing what the data means. You give it your semantic model in an open format (Apache Ossie, formerly OSI), your own metadata, context and documents — and it lets agents find the right tables, read what they mean and query them, safely.

Status: pre-alpha — working, and used on real warehouses; its interfaces may still change. Metrics, saved query sets and more databases are on their way (the plan).

What it does now

• ClickHouse, PostgreSQL, MySQL and DuckDB, configured in one YAML file: the tables agents may read, the large tables a query must bound (and the columns it must name values of — an event log of every kind of event), limits per query; secrets by variable name, never written in it.

• Read-only, checked twice: one SELECT at a time, parsed for the database's own dialect by sqlglot and by the database itself; only the tables you allow, wherever they are read; large tables bounded; rows and time capped, never cut without saying so — on top of a read-only database user. Every answer carries the SQL as it ran and when.

• A semantic layer in Apache Ossie: datasets, fields, relationships and metrics, with ai_context for agents and custom_extensions for anything of your own — categories, layers, links to code, owners — checked against a vocabulary you declare and served with what each value means — and lists filtered by it, with the menu of its values.

• An importer from dbt: semantic-warehouse-mcp import-dbt writes your dbt project's tables, descriptions, meta and tags as an Ossie model — with what each model reads and its SQL, if you want them; the tables chosen by name or as dbt selects them (tag:daily, path:models/marts); the mapping yours, in its configuration.

• A draft from the database itself, where no dbt project describes it: semantic-warehouse-mcp import-database writes its readable tables, columns and comments as an Ossie model for you, or an agent, to give meaning to.

• Your own context and skills: instructions, documents and skills (the Agent Skills format: a folder with a SKILL.md and the files it refers to) served to agents as written — from disk, or straight from a git repository, kept fresh.

• Any MCP client: stdio for one person's agent, Streamable HTTP for a server a team shares (a token on every request, /health, a container image).

Related MCP server: sql-steward

Install

Each engine's driver is an extra — postgres, mysql, duckdb, or all (ClickHouse needs none):

uvx --from 'semantic-warehouse-mcp[all]' semantic-warehouse-mcp --config config.yaml --check   # check, reach every database
uvx --from 'semantic-warehouse-mcp[all]' semantic-warehouse-mcp --config config.yaml           # serve over stdio
pip install 'semantic-warehouse-mcp[postgres]'                                                  # or install it

Connect Claude Code (any client that runs stdio servers takes the same command):

claude mcp add warehouse -- uvx --from 'semantic-warehouse-mcp[all]' semantic-warehouse-mcp --config /path/to/config.yaml

Documentation

swm.pipelab.dev — the guide, built from docs/:

• Getting started — from nothing to an agent answering about a made-up shop's data.

• The guide: tools, configuration, semantic models and vocabularies, the dbt importer, the guard, engines, running it.

Why

An agent with a bare SQL connection writes plausible queries over the wrong tables. What makes its answers right is semantics: what a table holds, which column is the date, how a metric is defined, what not to mix. That knowledge already exists in teams — in dbt projects, semantic layers, wikis — but every tool wants it in its own shape. This server reads it in an open, vendor-neutral format and serves it beside the data.

Development

Python 3.12, uv, the official MCP Python SDK.

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run python examples/data/make_shop.py    # the made-up shop the examples describe
uv run semantic-warehouse-mcp --config examples/config.example.yaml   # the server over stdio

License

Apache-2.0.