# hypequery MCP server

> Lets AI agents list your defined ClickHouse datasets and metrics, inspect schemas, and run governed analytics queries without raw SQL.

- Repository: https://github.com/hypequery/hypequery
- Page: https://hostedmcp.org/servers/hypequery/hypequery
- Transport: stdio
- Stars: 106

## Install

### Claude Code

```sh
claude mcp add hypequery -- npx -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"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"hypequery","type":"stdio","command":"npx","args":["-y","@hypequery/mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

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

### Codex

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

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.hypequery]
command = "npx"
args = ["-y", "@hypequery/mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user hypequery npx -- -y @hypequery/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

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

## FAQ

### What tools does the hypequery ClickHouse MCP server expose to agents?

Agents can call list_datasets, get_dataset_schema, query_metric and query_dataset against the datasets and metrics you define. There is no raw SQL tool.

### How do I add the hypequery MCP server to Claude Code?

Install the packages and run the claude mcp add command pointing at @hypequery/mcp with your config file. You can try it against the public ClickHouse playground first.

### Does the hypequery MCP server let agents write arbitrary SQL?

No. Only approved analytics datasets and metrics are exposed as bounded tools.

### Is tenant scoping enforced for MCP queries?

Yes, tenant scope is applied at runtime and fails closed rather than depending on each query author to add a filter.

### Which agents does the hypequery MCP server work with?

It is designed for Claude Code, Cursor, Codex and other agents.
