hypequery MCP server

What it does

@hypequery/mcp is the MCP part of hypequery, an open-source TypeScript semantic layer and query builder for ClickHouse. You describe datasets and named metrics (revenue, orders and so on) in your own TypeScript code, publish the ones an agent may use, and the server turns that published catalog into four tools: one to list datasets, one to describe a dataset's dimensions, measures, metrics and relationships, one to run a named metric, and one to query the published fields of a dataset. The agent never writes SQL and never sees the database credentials, which stay in the server process.

Queries are validated against the same catalog that produces the tool schemas. Every query gets a server-side row limit even when the agent sets none, and calls have a time deadline and a response-size ceiling. Generated SQL is left out of responses unless the host turns on the includeSql option, and backend errors are reduced to a generic code rather than passed to the agent.

There are two ways to run it. The hypequery-mcp command starts a stdio server from a compiled config file that exports datasets and analytics. Its source (src/bin.ts at 0.9.0) reads only the --config flag and passes nothing else, so the tenant ID, custom query limits, execution budgets and includeSql are only available when you start the server from your own code with createMCPServer or embed it in another transport with createMCPExecutor. Besides the tools, the server also offers a dataset guide prompt (src/executor.ts).

What it needs

Node.js and an existing hypequery project: @hypequery/mcp, @hypequery/datasets and @hypequery/clickhouse installed (npm install @hypequery/mcp @hypequery/datasets @hypequery/clickhouse), a ClickHouse database the project connects to, and a config file you write and compile to JavaScript that exports datasets and analytics. The server starts nothing useful without that file.

Limits

It only answers queries over the datasets, fields and metrics you have published; there is no free-form SQL tool and no tool that changes data. The hypequery-mcp command accepts only --config, so tenant scoping, lower query limits, timeouts and SQL debug output need the programmatic API (createMCPServer). Limits you configure can lower the package's built-in ceilings but not raise them. The package creates no HTTP endpoint: a hosted setup must bring its own transport and sign-in. The docs' client snippet uses npx hypequery-mcp, which finds the program only when the package is installed in the project; the snippet here names the package so it also works from elsewhere.

Who it suits

Teams that already model ClickHouse analytics in TypeScript with hypequery, or are willing to, and want an assistant to answer questions with the same metric definitions their backend and dashboards use, without handing it raw SQL access. Multi-tenant products that need per-customer scoping should plan to run it from their own code, not the CLI. If you just want an assistant to explore a ClickHouse database with ad-hoc SQL and no modelling step, a general ClickHouse server fits better; this one does nothing until you have written a semantic layer.