hypequery MCP Server: Setup for Claude, Cursor and Other Apps
Lets Claude or Cursor answer questions from the ClickHouse metrics and datasets you publish with hypequery, without raw SQL access.
This is the hypequery project's own server. It turns the datasets and metrics you define in TypeScript into four read-only tools. The assistant asks for revenue or order data and gets rows back, and your ClickHouse credentials stay in the server process.
It runs on your machine over stdio and needs a small config file that exports your datasets and ClickHouse client. That makes it a fit for developers, not a one-click connector. A Python backend can also feed it through an HTTP endpoint.
Good for
- Developers who already use hypequery on ClickHouse
- Data teams who want an assistant to use approved metrics, not free SQL
- Teams serving per-customer analytics who need tenant limits
Works in
12 should work
Tap an app to see how to set it up and any known problems.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Client does not support this transport.
Client does not support this transport.
Install hypequery MCP
Claude Code
- 1
Copy this prompt.
Add the hypequery MCP server to Claude Code. Run this command: claude mcp add hypequery -- npx -y @hypequery/mcp --config /absolute/path/to/mcp-config.js Then check that it loaded and tell me if I need to sign in or restart.
- 2
Paste it into Claude Code. It shows the change and asks before running it.
Requires Node.js, Compiled mcp-config.js.
Read-only mode: All four tools are read-only already, so there is nothing to switch on.
Replace the path with your compiled config file. The README starts the server with its bin name and a config path; this form runs the package by its scoped name. Do not use the README's short form npx hypequery-mcp: there is no npm package with that name (checked 2 Nov 2026), so outside a project that has @hypequery/mcp installed, npx would fetch whatever someone publishes under that name. Always use the scoped name @hypequery/mcp.
Built from the package data we hold. Not yet tested by us.
Tools
Lists the datasets you have published
Returns the names and descriptions of every dataset in your published semantic layer, so the assistant knows what it can ask about.
Try: “What datasets can you query?”
Read ·
list_datasetsShows a dataset's fields and metrics
Returns the dimensions, measures, named metrics, filters and relationships of one dataset, so the assistant builds valid queries.
Try: “Describe the orders dataset.”
Read ·
get_dataset_schemaRuns a named metric such as revenue
Runs a named KPI that you defined, with the grouping and filters you allow, and returns rows with count, timing and paging data.
Try: “Show revenue by region for the last month.”
Read ·
query_metricExplores the fields you chose to publish
Queries a dataset using only the dimensions, measures, filters and ordering you published, with a server-side row limit added if the assistant gives none.
Try: “List the ten biggest orders this week by customer.”
Read ·
query_dataset
Read from the source code
Permissions
low risk · 4 things to watch
Low risk
The assistant can read any dataset and field you publish, and nothing else. Publish only data you are happy for it to see, and set a tenant ID in code if you serve several customers.
What it can do
- Read your data
- Create and change things
- Delete things
- Read-only modeHow to turn it on
Watch out for
It runs your config file as code
The server imports the config file you point it at, so that file runs on your machine with your ClickHouse access. Only use configs you wrote or reviewed. github.com
It can read everything you publish
Any published dataset and field can be queried by the assistant, so publish only data you are happy to share with it. For per-customer data, set a trusted tenant ID in code. github.com
Use the scoped package name, not hypequery-mcp
The README starts the server with `npx hypequery-mcp`, a bin name. No npm package called hypequery-mcp exists (checked 2 Nov 2026), so without a local install of @hypequery/mcp that command would run whatever someone registers under that name. The package is @hypequery/mcp, published by the npm user lureilly2, and the install box uses that name. npmjs.com
Setup needs code
You write a config that publishes datasets with the hypequery packages, then compile it, before the server can start. github.com
Security advisories
No published security advisories as of Nov 1, 2026.
Technical details
| Turning on read-only | All four tools are annotated read-only and non-destructive in the source. Only the datasets and fields you publish can be queried. |
|---|---|
| Talks to | Your ClickHouse server, from the machine running the server |
| Sign-in and keys | ClickHouse credentials live in your own config file and stay in the server process. |
Questions
Is the hypequery MCP server official?
Yes. It is part of the hypequery project, in the packages/mcp-server folder of the hypequery repository, and works with hypequery datasets and metrics.
Do I need an API key?
No. The server needs no sign-in. It uses the ClickHouse connection you set in your own config file, so the key is a ClickHouse login.
Can it change or delete data?
No. All four tools are marked read-only and non-destructive in the source, and queries are limited to the datasets and fields you publish.
Can it run SQL for me?
No. The assistant picks from published metrics and fields. The README says SQL text stays hidden by default and tenant identity comes from trusted host config, not the prompt.
Is it local or hosted?
Local. It runs on your machine over stdio. A Python backend with an HTTP endpoint can feed it, but the README describes remote hosting and sign-in as a separate concern.
What do I need before I can use it?
You need a hypequery project with datasets published through its packages, and a compiled config file that exports your datasets and ClickHouse client. The install box shows the command that points the server at that file.
Information
updated Nov 2, 2026
- Publisher
- Official
- Package
@hypequery/mcp- Registry
- npm
- Transport
- stdio
- Auth
- None
- Version
- 0.11.0
- License
- Apache-2.0
- Last commit
- Oct 30, 2026
- Open issues
- 2
Sources
Docs, issue trackers and discussions this page is built from. Issues, quotes and findings above link to their own source.
Show all 4Hide
- github.com · github.com
- github.com · github.com
- github.com · github.com
- www.npmjs.com · npmjs.com