# hypequery ClickHouse

hypequery ClickHouse — an MCP server for Claude Code that connects agents to ClickHouse via governed datasets and metrics. It blocks raw SQL execution and hides direct database credentials.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 106 repo stars
- Author: hypequery
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/hypequery/hypequery/tree/HEAD/packages/mcp-server
- Updated: 2026-11-16
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/hypequery-clickhouse

## What it does

Exposes analytical schemas to assistants through four dedicated tools: `list_datasets`, `get_dataset_schema`, `query_metric`, and `query_dataset`. Models inspect predefined metrics and dimensions instead of constructing arbitrary database queries.

The server launches locally via a compiled Node.js configuration file or connects to an existing Python backend using `hypequery.serve`. When integrating with Python over HTTP, it requires `HYPEQUERY_CLIENT_CONTRACT_URL` and `HYPEQUERY_API_KEY`.

HTTP execution enforces a 30-second budget, a 1 MiB response ceiling, and a maximum of 1,000 returned rows. Internal database exceptions and underlying SQL syntax stay redacted behind `MCP_EXECUTION_FAILED`.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add mcp-server -- npx -y @hypequery/mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add mcp-server -- npx -y @hypequery/mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "@hypequery/mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@hypequery/mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add mcp-server npx -y @hypequery/mcp
```

## When to use it
- block agents from running unconstrained SQL queries in ClickHouse
- calculate business KPIs using standardized metric definitions
- inspect schema structures and table relationships safely
- enforce strict data transfer caps and query execution timeouts

## Example prompts
- List available ClickHouse datasets and their descriptions
- Query monthly revenue broken down by region using query_metric
- Inspect dimensions and measures for the Orders dataset

## Similar
- [clickhouse-query](https://affpapa.org/en/nevibecode/skills/clickhouse-query.md) — skill · ★ 7327 repo stars
- [clickhouse-best-practices](https://affpapa.org/en/nevibecode/skills/clickhouse-best-practices.md) — skill · 23400 installs
- [ClickHouse](https://affpapa.org/en/nevibecode/mcp/clickhouse.md) — MCP server · ★ 913 repo stars
- [clickhouse-io](https://affpapa.org/en/nevibecode/skills/clickhouse-io.md) — skill · 6200 installs
- [clickhouse-architect](https://affpapa.org/en/nevibecode/skills/clickhouse-architect.md) — skill · 157 installs
- [clickhouse-cloud-management](https://affpapa.org/en/nevibecode/skills/clickhouse-cloud-management.md) — skill · 126 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
