MCP server de hypequery
Commit 15 nov 2026Permite que los agentes de IA listen tus datasets y métricas de ClickHouse definidos, inspeccionen esquemas y ejecuten consultas analíticas gobernadas sin necesidad de SQL puro.
También conocido como hypequery/hypequery, @hypequery/mcp, @hypequery/datasets
- Stars
- 106
- Herramientas
- —
- Descargas, 30 días
- 108.251
- Última versión
- —
- Último commit
- 15 nov 2026
- Licencia
- —
¿Qué es hypequery MCP?
hypequery es un MCP server. Permite que los agentes de IA listen tus datasets y métricas de ClickHouse definidos, inspeccionen esquemas y ejecuten consultas analíticas gobernadas sin necesidad de SQL puro.
Resumen generado a partir del README del proyecto
Acerca del MCP server de hypequery
hypequery permite que los agentes de IA realicen analítica gobernada sobre datasets de ClickHouse. En lugar de proporcionar acceso sin restricciones a SQL puro, este MCP server expone dimensiones, medidas y métricas específicas definidas en tu código. Los ingenieros pueden desplegar esto como un conjunto de librerías Apache 2.0 dentro de su propio backend para garantizar que los agentes interactúen únicamente con estructuras de datos aprobadas.
Los usuarios integran el servidor instalando el paquete @hypequery/mcp y configurándolo con un archivo de configuración local. Una vez configurado, agentes como Claude Code o Cursor pueden utilizar herramientas específicas como list_datasets, get_dataset_schema, query_metric y query_dataset. Esta configuración asegura que las reglas de tenant y las definiciones de métricas se mantengan consistentes en dashboards, APIs y herramientas de IA sin tener que escribir SQL manualmente. Está diseñado para desarrolladores que trabajan con TypeScript o Python y necesitan una capa semántica que conviva con el código de su aplicación.
Qué puedes hacer con él
- 1Mantener la seguridad multi-tenantEl sistema garantiza que las consultas de IA respeten los límites de tenant definidos en tu código para evitar la filtración de datos.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Cómo instalar hypequery MCP
Formatos verificados el 10 nov 2026Añadir a CursorAñadir a GooseInstalar hypequery MCP en Claude Code
$ claude mcp add hypequery -- npx -y @hypequery/mcpInstalar hypequery MCP en Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hypequery": {
"command": "npx",
"args": [
"-y",
"@hypequery/mcp"
]
}
}
}Instalar hypequery MCP en VS Code
.vscode/mcp.json
{
"servers": {
"hypequery": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@hypequery/mcp"
]
}
}
}Instalar hypequery MCP en VS Code CLI
$ code --add-mcp '{"name":"hypequery","type":"stdio","command":"npx","args":["-y","@hypequery/mcp"]}'Instalar hypequery MCP en Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"hypequery": {
"command": "npx",
"args": [
"-y",
"@hypequery/mcp"
]
}
}
}Instalar hypequery MCP en Codex
$ codex mcp add hypequery -- npx -y @hypequery/mcpInstalar hypequery MCP en Codex config.toml
~/.codex/config.toml
[mcp_servers.hypequery] command = "npx" args = ["-y", "@hypequery/mcp"]
Instalar hypequery MCP en Gemini CLI
$ gemini mcp add -s user hypequery npx -- -y @hypequery/mcpInstalar hypequery MCP en Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hypequery": {
"command": "npx",
"args": [
"-y",
"@hypequery/mcp"
]
}
}
}Verificaciones automáticas
Ejecutado 13 nov 2026Informe completo →Aún no verificado. Un servidor necesita una puntuación de 80, ningún hallazgo grave y suficientes datos para que podamos revisarlo. Cómo funcionan las verificaciones · Qué corregir para obtener más puntos
- Repositorio de origen vinculado y accesiblehypequery/hypequery is public and reachablegithub.com/hypequery/hypequery ↗Aprobado
- El paquete indica este repositorio como su origen@hypequery/mcp, @hypequery/datasets name hypequery/hypequery as sourcenpmjs.com/package/@hypequery/mcp ↗Aprobado
- Procedencia de la compilación (atestación de Sigstore)No build attestation published for this releaseNo verificado
- Licencia de código abierto (OSI)No licenseHallazgo
- Commit o lanzamiento en el último añoLast commit or release 2026-11-12github.com/hypequery/hypequery ↗Aprobado
- OpenSSF ScorecardNo verificado
- El nombre del paquete no es similar a un paquete popularNo popular package one edit away from @hypequery/mcp, @hypequery/datasetsAprobado
- No hay avisos críticos en el paquete ni en sus dependenciasNo verificado
- Sin instrucciones ocultas para el modelo0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersAprobado
- Las herramientas destructivas están etiquetadasNo verificado
- El endpoint remoto responde al handshake de MCPNo verificado
README
Ver en GitHubDefine 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.
Start in minutes (TypeScript)
npm install -D @hypequery/cli
npx hypequery init
npx hypequery dev
Or add only the ClickHouse query builder:
npm install @hypequery/clickhouse
const 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 quickstart, 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"
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 |
|---|---|
@hypequery/clickhouse |
Type-safe ClickHouse query builder |
@hypequery/datasets |
TypeScript semantic layer |
@hypequery/serve |
Validated analytics APIs and OpenAPI |
@hypequery/react |
Typed React hooks |
@hypequery/mcp |
Governed ClickHouse MCP server |
@hypequery/cli |
Setup, generation, local docs, and deployment |
hypequery (PyPI) |
Python datasets, execution, Serve, and CLI (beta) |
Explore
- What hypequery supports today
- ClickHouse semantic layer
- Multi-tenant analytics
- React hooks
- MooseStack EOL comparison
- MooseStack migration guide
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.
Preguntas sobre hypequery MCP
¿Cómo agrego hypequery MCP a Claude Code?
Ejecuta claude mcp add hypequery -- npx -y @hypequery/mcp en tu terminal. Añade --scope user para que esté disponible en todos los proyectos.
¿Cómo agrego hypequery MCP a Cursor?
Abre ~/.cursor/mcp.json y añade el servidor en mcpServers, usando la configuración de Cursor que se muestra en la sección de instalación de arriba.
¿Qué herramientas expone el MCP server de hypequery para ClickHouse a los agentes?
Los agentes pueden llamar a list_datasets, get_dataset_schema, query_metric y query_dataset sobre los datasets y métricas que tú definas. No existe una herramienta de SQL puro.
¿Cómo añado el MCP server de hypequery a Claude Code?
Instala los paquetes y ejecuta el comando claude mcp add apuntando a @hypequery/mcp con tu archivo de configuración. Puedes probarlo primero con el playground público de ClickHouse.
¿Permite el MCP server de hypequery que los agentes escriban SQL arbitrario?
No. Solo se exponen datasets y métricas analíticas aprobadas como herramientas delimitadas.
¿Se aplica el aislamiento de tenants en las consultas MCP?
Sí, el alcance del tenant se aplica en tiempo de ejecución y falla por defecto en lugar de depender de que cada autor de la consulta añada un filtro.
¿Con qué agentes es compatible el MCP server de hypequery?
Está diseñado para Claude Code, Cursor, Codex y otros agentes.