# hypequery ClickHouse

> hypequery ClickHouse is an MCP server for databases. Let agents query named ClickHouse datasets and metrics without handing them raw SQL. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Platforms:** CLI, API
- **Website:** https://hypequery.com/docs/mcp/overview
- **Repository:** https://github.com/hypequery/hypequery/tree/HEAD/packages/mcp-server
- **MCP Registry name:** io.github.hypequery/hypequery
- **Categories:** [databases](https://ai-powered.com/categories/databases), [analytics and data](https://ai-powered.com/categories/analytics-and-data)
- **Listing updated:** 2026-11-18

## About

The server draws a hard line around what an agent can touch. Only datasets you register and metrics you attach to them are exposed, and agents can inspect dimensions, labels, descriptions, filters, tenant keys and time keys before querying. The registry description sums it up: named datasets and metrics as tools, never raw SQL.

It runs over stdio by default, with an `--http` flag for a URL. `npx hypequery mcp` serves the datasets of a TypeScript API, `hypequery mcp app:api` does the same for a Python backend, and a `--client-contract-url` option points at an API that is already deployed. If a dataset has a tenantKey, the server refuses to start without a trusted tenant such as `--tenant acme`, and `--self-test` checks the setup first.

The docs are clear that MCP here is a capability boundary, not an authentication layer, so multi-tenant data needs the safety model read first.

## Features

- **Governed datasets:** Exposes only registered datasets and attached metrics.
- **Schema inspection:** Agents can read dimensions, labels, filters, tenant keys and time keys.
- **Tenant guard:** Refuses to start without a trusted tenant when a dataset has a tenantKey.
- **TypeScript and Python:** Serves datasets from either a TypeScript or a Python hypequery API.
- **Self-test mode:** Validates the setup and counts exposed endpoints without running queries.
- **Stdio or HTTP:** Defaults to stdio; add --http to serve at a URL.

## Good for

- Ask Claude or Cursor for revenue by region using the same metric your dashboards use
- Give an analyst agent access to ClickHouse without a SQL console
- Expose multi-tenant analytics to an agent as one trusted tenant
- Print an mcpServers config entry with --print-config

## Install

### Claude Code (Terminal)

```sh
claude mcp add hypequery -- npx -y @hypequery/mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "hypequery": {
      "command": "npx",
      "args": [
        "-y",
        "@hypequery/mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "hypequery": {
      "command": "npx",
      "args": [
        "-y",
        "@hypequery/mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "hypequery": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@hypequery/mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "hypequery": {
      "command": "npx",
      "args": [
        "-y",
        "@hypequery/mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "hypequery": {
      "command": "npx",
      "args": [
        "-y",
        "@hypequery/mcp"
      ]
    }
  }
}
```

## FAQ

### Can the agent run arbitrary SQL?

No. It works through named datasets and metrics, and the API keeps ownership of SQL.

### Does it replace authentication?

No. The docs say MCP is a capability boundary, not an authentication layer.

### How do I check my setup?

Run hypequery mcp with --self-test. It validates the contract and counts the endpoints it would expose without calling any query tool.

### Is there a hosted option?

The overview lists hypequery Cloud, where every release has an /mcp endpoint.

### How do I add hypequery ClickHouse to Claude Code?

Run this command in your terminal: claude mcp add hypequery -- npx -y @hypequery/mcp

### What are the best alternatives to hypequery ClickHouse?

The closest alternatives to hypequery ClickHouse are Agent-Native Analytics, Google Ads + Meta Ads + SEO/GEO MCP, dashboard-icons, Tapetide - Indian Stock Market MCP and Midplane.

## Where this comes from

- Description: written from the project's README and the project's website.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Agent-Native Analytics](https://ai-powered.com/mcp/agent-native-analytics): Agent-Native Analytics is an open-source MCP server for analytics and data.
- [Google Ads + Meta Ads + SEO/GEO MCP](https://ai-powered.com/mcp/google-ads-meta-ads-seo-geo-mcp): Google Ads + Meta Ads + SEO/GEO MCP is a freemium MCP server for marketing and seo.
- [dashboard-icons](https://ai-powered.com/mcp/dashboard-icons): dashboard-icons is an open-source MCP server for analytics and data.
- [Tapetide - Indian Stock Market MCP](https://ai-powered.com/mcp/tapetide-indian-stock-market-mcp): Tapetide - Indian Stock Market MCP is a freemium MCP server for finance and payments.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [World Monitor](https://ai-powered.com/mcp/world-monitor): World Monitor is a freemium MCP server for analytics and data.
- [DataArcus for Power BI](https://ai-powered.com/mcp/dataarcus-for-power-bi): DataArcus for Power BI is a free MCP server for analytics and data.
- [CompanyData](https://ai-powered.com/mcp/companydata): CompanyData is a paid MCP server for analytics and data.

---
Source: https://ai-powered.com/mcp/hypequery-clickhouse
