hypequery
OfficialProvides governed access to ClickHouse datasets and metrics, allowing agents to list datasets, inspect dataset schemas, and query approved metrics or datasets without exposing raw SQL.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Define your metrics once, in the codebase you already have. Dashboards, APIs, and AI agents all answer from that one definition. Run it in your own backend today. A hosted option, hypequery cloud, is coming soon.
hypequery is an open-source embedded analytics toolkit for ClickHouse that runs inside your own application. You define datasets in TypeScript or Python (beta), with their dimensions, measures, metrics, and tenant rules, then query them by name and serve them as authenticated HTTP endpoints with OpenAPI, typed React hooks, and MCP tools for AI agents. The TypeScript SDK also includes a type-safe ClickHouse query builder. It is for engineers building dashboards, APIs, and agent tools on their own ClickHouse. hypequery is not a hosted BI tool, not a database, and not a separate semantic-layer server: it is a set of Apache 2.0 libraries you install and deploy with your backend.
One definition, every surface
import { dataset, dimension, measure } from '@hypequery/datasets';
export const Orders = dataset('orders', {
source: 'orders',
tenantKey: 'tenant_id',
timeKey: 'created_at',
dimensions: {
region: dimension.string(),
status: dimension.string(),
createdAt: dimension.timestamp({ column: 'created_at' }),
},
measures: {
revenue: measure.sum('amount'),
orderCount: measure.count('id'),
p95OrderValue: measure.percentile('amount', 0.95),
},
});
export const revenue = Orders.metric('revenue', {
measure: 'revenue',
});That dataset can run in a worker, become a validated HTTP endpoint, power a typed React dashboard, or appear as a bounded MCP tool. Tenant scope and metric meaning stay in one place.
Related MCP server: bonnard
Start in minutes (TypeScript)
npm install -D @hypequery/cli
npx hypequery init
npx hypequery devOr add only the ClickHouse query builder:
npm install @hypequery/clickhouseconst revenueByRegion = await db
.table('orders')
.select(['region'])
.where('status', 'eq', 'completed')
.sum('amount', 'revenue')
.groupBy('region')
.orderBy('revenue', 'DESC')
.execute();No hand-written result interface. No any[]. The result is inferred from your real schema and the query itself.
Python (beta)
The Python SDK implements the same datasets and Serve protocol, checked against the same conformance fixtures. Serve it from FastAPI, Django, Flask, or any ASGI or WSGI server.
pip install "hypequery[clickhouse]==0.1.0b2"from hypequery.datasets import Dataset, DatasetQuery, ExecutionContext, create_dataset_client, dimension, measure, tenant
from hypequery.execution import ClickHouseConnection, create_clickhouse_executor
orders = Dataset(
name="orders",
source="orders",
tenant_key="tenant_id",
dimensions={"country": dimension("string")},
measures={"revenue": measure.sum("amount")},
)
analytics = create_dataset_client(executor=create_clickhouse_executor(ClickHouseConnection.from_env()))
result = analytics.execute(
orders,
DatasetQuery(dimensions=("country",), measures=("revenue",)),
context=ExecutionContext(tenant=tenant("org_123")),
)See the Python docs and python/hypequery.
ClickHouse MCP server
@hypequery/mcp is a governed ClickHouse MCP server for Claude Code, Cursor, Codex and other agents. Agents call list_datasets, get_dataset_schema, query_metric and query_dataset against the datasets and metrics you define; there is no raw SQL tool. To try it against the public ClickHouse playground in five minutes, install the packages, save the mcp-config.mjs from the Claude Code guide, and add the server to your agent:
npm install @hypequery/mcp @hypequery/datasets @hypequery/clickhouse
claude mcp add clickhouse -- npx -y @hypequery/mcp --config "$PWD/mcp-config.mjs"Setup for Claude Desktop, Cursor and Codex, and how it compares with ClickHouse's own MCP servers, is on hypequery.com/clickhouse-mcp.
Built for product analytics
ClickHouse-native: generated types plus
FINAL,LIMIT BY, percentiles,argMax, arrays, CTEs, streaming, and window expressions.Governed in code: dimensions, measures, metrics, relationships, and time grains live beside your application.
Multi-tenant by design: runtime tenant scope fails closed instead of relying on every query author to remember a filter.
Frontend ready: typed TanStack Query hooks for named queries, metrics, and datasets.
Agent ready: MCP tools expose approved analytics, not unrestricted SQL.
Two languages, one contract: TypeScript and Python produce the same semantic and deployment artifacts.
Easy to adopt: start with one local query and add the semantic, HTTP, React, or MCP layers only when needed.
Packages
Package | Job |
Type-safe ClickHouse query builder | |
TypeScript semantic layer | |
Validated analytics APIs and OpenAPI | |
Typed React hooks | |
Governed ClickHouse MCP server | |
Setup, generation, local docs, and deployment | |
| Python datasets, execution, Serve, and CLI (beta) |
Explore
If hypequery saves you from another copied SQL string or drifting metric, a GitHub star helps the next team find it.
License
Apache-2.0. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.
Hosted MCP server for RudderStack, the agentic CDP that runs on your warehouse. Ask Claude, ChatGPT, Cursor or Codex why events failed, which warehouse loads broke, or where your tracking plan is violated. Build and test transformations and audiences. OAuth login, your permissions, PII masked.
Hosted MotherDuck MCP server: explore data, run DuckDB SQL, and build Dives and Flights.
Related MCP Servers
FlicenseNot gradedqualityBmaintenanceProduction-ready MCP server designed to empower AI agents and LLMs to interact seamlessly with ClickHouse. It exposes your ClickHouse database as a set of standardized tools and resources that adhere to the MCP protocol, making it easy for agents built on OpenAI, Claude, or other platforms to query, explore, and analyse your data.39-
bonnardofficial
AlicenseNot gradedqualityFmaintenanceOpen-source agentic schema layer. Define metrics once in YAML, query governed data from any warehouse (Snowflake, BigQuery, Databricks, PostgreSQL, DuckDB) via MCP.28Apache 2.0- FlicenseNot gradedqualityCmaintenanceA production-ready MCP agent that helps data teams define, validate, and visualize semantic metrics with enterprise-grade persistence, trust scoring, and BI integrations.5-
- AlicenseAqualityDmaintenanceA DataOps-focused MCP server for ClickHouse that provides query optimization advice, pipeline latency analysis, and data quality monitoring, with read-only safety.825 PyPIMIT