chdb-mcp
OfficialThe chdb-mcp server provides an MCP interface to chDB, an in-process ClickHouse SQL OLAP engine, letting AI agents run analytical SQL queries against local files, in-memory data, and remote sources without a separate server or Docker setup.
Tools available:
query(sql, format)— Execute read-only SQL (SELECT/SHOW/DESCRIBE/EXPLAIN) using ClickHouse SQL dialect; supports output formats likeJSONCompact,CSVWithNames,Pretty, etc. Write access enabled viaCHDB_MCP_WRITE=1.list_databases()— Enumerate all databases visible to the current chDB session.list_tables(database)— List all tables within a specified database.describe_table(database, table)— Retrieve column names and types for a specific table.query_file(path, sql, format)— Query local files (Parquet, CSV, JSON, Arrow, etc.) directly using SQL with a{file}placeholder.get_sample_data(database, table, limit)— Fetch the first N rows (up to 1,000) from a table as a quick preview.list_functions(pattern)— Browse 1,000+ ClickHouse SQL functions with optional substring filtering.
Key characteristics:
Read-only by default — writes blocked unless
CHDB_MCP_WRITE=1is set.Configurable safety limits — result size cap (default 1 MiB) and query timeout (default 30s).
File allowlist — restrict file/URL/S3 access to specific path prefixes via
CHDB_MCP_FILE_ALLOWLIST.Broad data source support — Parquet, CSV, JSON, Avro, ORC, Arrow, S3, MongoDB, PostgreSQL, MySQL, Iceberg, Delta Lake, and more, natively in SQL.
Federation — query remote ClickHouse clusters and combine with local data sources.
pandas integration — zero-copy data processing with pandas DataFrames.
Allows querying local and remote ClickHouse databases with full ClickHouse SQL syntax and functions, including federation via remoteSecure().
Enables direct SQL queries on MongoDB collections using the mongodb() table function.
Enables direct SQL queries on MySQL tables using the mysql() table function.
Provides a pandas-like API and zero-copy DataFrame querying, enabling SQL queries on pandas DataFrames.
Enables direct SQL queries on PostgreSQL tables using the postgresql() table function.
Allows querying Prometheus metrics via prometheusQuery* table functions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@chdb-mcp Query sales.parquet for total revenue by region"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
chdb-mcp
This project is superseded by mcp-clickhouse.
chDB support now ships in the official ClickHouse MCP server: install with
pip install 'mcp-clickhouse[chdb]', set CHDB_ENABLED=true (and CHDB_DATA_PATH
for persistence), and agents get a run_chdb_select_query tool backed by embedded
chDB — standalone or alongside a ClickHouse server connection. It can be enabled with
configuration only, matching the ClickHouse MCP experience.
chdb-mcp remains available on PyPI but is no longer the recommended entry point
and will only receive critical fixes.
An MCP server for chDB, the in-process SQL OLAP engine powered by ClickHouse. Lets agents (Claude Desktop, Cursor, VS Code, Codex CLI, Cline, …) query Parquet, CSV, JSON, and pandas DataFrames with one tool — no separate server, no Docker.
Why chdb-mcp?
Full ClickHouse engine, in-process. 1000+ functions (
windowFunnel,quantilesTDigest,geoToH3, the-If/-State/-Mergecombinators), typedJSONwith O(1) sub-column reads, native vectors,MergeTreestorage.Drop-in pandas API.
import datastore as pdcovers ~300 pandas-shaped methods compiled to ClickHouse SQL. v1.0 addsdataframe_query()for zero-copyPython(df).~80 formats and 12+ source connectors in core. Parquet, CSV, JSON, Avro, ORC, Arrow, Protobuf, plus
s3(),mongodb(),postgresql(),mysql(),iceberg(),deltaLake()— noINSTALL/LOADchain.Federate to remote ClickHouse in one statement. (v0.5)
remoteSecure('cluster:9440', 'db.table', ...)joins local Parquet with a production ClickHouse cluster in one optimised plan.Same SQL as your warehouse. Copy-paste ClickHouse production queries into the agent prompt — no dialect bridge.
Related MCP server: Altinity MCP
Install
pip install chdb-mcpConnect
Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{ "mcpServers": { "chdb": { "command": "chdb-mcp" } } }Cursor / VS Code — same JSON in ~/.cursor/mcp.json etc.; one-click badges land in v0.2.
Codex CLI / Claude Code / Copilot / Droid — use the cross-IDE bundle chdb-agent-plugin.
Tools (v0.1)
Tool | Description |
| Run any read-only SQL on the in-process session |
| Enumerate visible databases |
| List tables in a database |
| Column types for a table |
| Query a Parquet/CSV/JSON file via the |
| First N rows of a table |
| List ClickHouse SQL functions (optional substring filter) |
Read-only by default — SET readonly=2 blocks INSERT/CREATE/DROP/ALTER while keeping file()/url()/s3() usable. Set CHDB_MCP_WRITE=1 to drop the guard. See Security model.
In query_file, {file} is replaced with file('path', 'format') before execution:
query_file(
path="/data/sales.parquet",
sql="SELECT region, sum(revenue) FROM {file} GROUP BY region",
format="Parquet",
)Configuration
Variable | Default | Effect |
| unset | If |
|
| Per-tool result cap. Enforced engine-side ( |
|
| Wall-clock cap per query (chDB |
| empty (unrestricted) |
|
| empty | Persistent session directory (default: ephemeral) |
Security model
chDB is in-process. There is no privilege boundary between the MCP server and the host Python interpreter, so the server can't make stronger isolation guarantees than the host already gives it. The model below reflects that.
Trust tiers
Default (no
CHDB_MCP_FILE_ALLOWLIST) — no filesystem gating.query()andquery_file()can reach anything the host process can reach (anyfile(),url(),s3(),remote()...). Appropriate when the agent is trusted, or when the surrounding host application enforces the security boundary itself.Opt-in allowlist (
CHDB_MCP_FILE_ALLOWLIST=/data:/tmp/foo) — best-effort defense in depth:query_file()rejects paths whose resolved (symlink-followed) form isn't under any listed prefix.Both
query()andquery_file()reject SQL containing any table function that isn't on the safe-by-construction list (numbers/values/view/merge/dictionary/generateRandom/...). The "known" set is snapshotted fromsystem.table_functionsat session start, so the gate stays in sync with whatever the running chDB build actually exposes — including new external-source variants (paimon*,prometheusQuery*,iceberg*Azure/S3/HDFS), RCE-class functions (executable,python), and*Clustersiblings, without a hand-maintained denylist that goes stale.For
query_file(), the scan runs on the user SQL before the{file}placeholder substitution, so aUNION ALL SELECT … FROM file('/etc/passwd', …)smuggled into the query body is caught even though the explicit path is gated.The scanner is comment- and string-aware (single-pass mask covering line comments, block comments, single-quoted strings with
''/\'/\\escapes), and it normalizes backtick- and double-quote-wrapped identifiers (`file`/"file") before matching so quoted function names can't bypass it.This is not a sandbox: a determined caller can still try to exfiltrate via undiscovered functions, settings, or future chDB features. Strong enough for casual agent mistakes, not for adversarial input.
Hard isolation — for adversarial input, wrap the server in OS-level confinement: macOS App Sandbox, Linux user namespaces / seccomp, or Docker with a read-only filesystem mount. Nothing at the MCP layer can substitute for this.
What's protected
Accidental writes —
SET readonly=2is applied at session start.CHDB_MCP_WRITE=1lifts it. (Note: ClickHouse'sreadonly=2still permitsTEMPORARY TABLEwrites and runtimeSETchanges — by design, not a bug.)Runaway result sizes —
CHDB_MCP_MAX_RESULT_BYTESis enforced engine-side (max_block_size+max_result_bytes+result_overflow_mode='break'), not just as a post-hoc string slice. Large queries no longer materialize multi-MiB in chDB before truncation.Runaway wall-clock —
CHDB_MCP_QUERY_TIMEOUT_SEC(default 30s) caps each query via chDB'smax_execution_time.SQL-identifier injection —
list_tables/describe_table/get_sample_dataarguments are whitelist-regex'd ([A-Za-z_][A-Za-z0-9_]*only) and backtick-quoted before interpolation.SQL string-literal escape —
list_functions(pattern)andquery_file(path, format)arguments are passed throughquote_string, which escapes both single quotes ('→'') and backslashes (\→\\) so that ClickHouse's\'escape form cannot break out of the literal.
What's NOT protected
SQL audit. Only the readonly guard — no allow/deny list of statements. Treat the agent as having full
SELECTaccess to anything chDB can reach (subject to the allowlist when set).Setting tampering. Under
readonly=2, the agent can stillSET max_memory_usage = …to raise resource caps. Lock this down at the host or via OS-level resource limits if it matters.Memory / CPU caps. chDB's
max_memory_usageapplies, but there's noulimit/cgroupsequivalent imposed by the MCP layer.
For agents acting on untrusted input, run in a throwaway container.
Roadmap
v0.5 —
query_remote_clickhouse()federation toolv1.0 —
attach_file(),dataframe_query()(zero-copyPython(df)), HTTP/SSE transport with Bearer auth,.mcpbbundle for Claude Desktop one-click install
Troubleshooting
macOS: "Server disconnected" in Claude Desktop
If ~/Library/Logs/Claude/mcp-server-chdb.log shows PermissionError: Operation not permitted on pyvenv.cfg, your venv sits under a TCC-protected directory (~/Downloads, ~/Documents, ~/Desktop) — Claude Desktop subprocesses can't read those paths.
Fix: install elsewhere. Recommended is uvx (zero-config, isolated under ~/.local/share/uv/):
{ "mcpServers": { "chdb": { "command": "uvx", "args": ["chdb-mcp"] } } }Or build a venv yourself under ~/.local/share/chdb-mcp/.venv and point Claude Desktop at its chdb-mcp binary.
query_file returns "path is not under any prefix"
The allowlist resolves symlinks on both sides (so /tmp matches /private/tmp on macOS). If you still hit this, check the resolved form printed in the error against python -c "from pathlib import Path; print(Path('YOUR_PATH').resolve())".
"Cannot execute query in readonly mode"
SET readonly=2 blocks DDL/DML by design. Rewrite as a pure SELECT, or restart with CHDB_MCP_WRITE=1.
Per-server logs
~/Library/Logs/Claude/mcp-server-chdb.log # startup diagnostics + stderr
~/Library/Logs/Claude/mcp.log # all servers' JSON-RPC trafficDevelopment
git clone https://github.com/chdb-io/chdb-mcp && cd chdb-mcp
pip install -e ".[dev]"
pytest && ruff check src testsLicense
Apache 2.0 — see LICENSE.
Available Tools
7 toolsdescribe_tableA
Return column types for a table.
Args: database: Database name (plain identifier). table: Table name (plain identifier).
Inputs: database (required), table (required). Returns: result
get_sample_dataA
Return the first N rows of a table.
Args:
database: Database name (plain identifier).
table: Table name (plain identifier).
limit: Maximum rows. Clamped to [1, 1000].
Inputs: database (required), table (required), limit. Returns: result
list_databasesA
List databases visible to the chDB session.
Returns one database name per line (TabSeparated format).
Inputs: no named parameters. Returns: result
list_functionsA
List SQL functions available in the chDB engine.
Returns name, is_aggregate, case_insensitive, alias_to for
each entry in system.functions — useful for agents discovering
ClickHouse's 1000+ function library (windowFunnel, quantilesTDigest,
-If/-State/-Merge combinators, etc.) in one round trip.
Args: pattern: Optional case-insensitive substring filter on the function name. Plain text only; SQL wildcards and quotes are escaped.
Inputs: pattern. Returns: result
list_tablesA
List tables in a given database.
Args: database: Database name. Must be a plain SQL identifier (letters, digits, underscore — no quotes, dots, or spaces).
Inputs: database (required). Returns: result
queryA
Execute an arbitrary SQL statement against the chDB session.
Use ClickHouse SQL dialect. Common formats: JSONCompact (default),
CSVWithNames, TabSeparatedWithNames, Pretty. The result is
truncated at CHDB_MCP_MAX_RESULT_BYTES (default 1 MiB) and the query
is aborted after CHDB_MCP_QUERY_TIMEOUT_SEC seconds (default 30).
Args:
sql: Any read-only SQL (SELECT/SHOW/DESCRIBE/EXPLAIN). Writes require
CHDB_MCP_WRITE=1. When CHDB_MCP_FILE_ALLOWLIST is set,
any table function that isn't on the safe-by-construction list
(numbers/values/view/merge/dictionary/etc.) is rejected — that
includes file/url/s3/remote/executable/python and every other
external-reach function chDB exposes. Use query_file() for
files instead.
format: Output format passed to chDB. Defaults to JSONCompact.
Inputs: sql (required), format. Returns: result
query_fileA
Query a local file (Parquet/CSV/JSON/…) as if it were a table.
The literal token {file} in sql is substituted with a
file('path', 'format') table-function call before execution.
Example::
query_file(
path="/data/sales.parquet",
sql="SELECT region, sum(revenue) FROM {file} GROUP BY region",
format="Parquet",
)Args:
path: Filesystem path. If CHDB_MCP_FILE_ALLOWLIST is set, the
resolved path must sit under one of its prefixes.
sql: Query body. Must contain the literal placeholder {file}.
When CHDB_MCP_FILE_ALLOWLIST is set, the SQL is scanned
before substitution; any extra table function call other than
the placeholder (e.g. a UNION with file('/etc/passwd', ...)
or a stray url()/executable()) is rejected.
format: chDB file format hint. Common values: Parquet, CSV,
CSVWithNames, JSONEachRow, Arrow.
Inputs: path (required), sql (required), format. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct operation: listing databases vs. tables vs. functions, describing a table, retrieving sample data, executing arbitrary queries, and querying files. No overlap in purpose.
All tool names follow a clear verb_noun pattern (list_databases, list_tables, describe_table, get_sample_data, query, query_file). The naming is predictable and uniform.
With 7 tools, the server is well-scoped for a database MCP server. It covers introspection, data querying, and file integration without being overly numerous or sparse.
The tool set covers essential database exploration and querying. The query tool can handle writes when enabled, and file querying is included. Minor missing features like a dedicated DDL tool exist but are workable via raw SQL.
Maintenance
Related MCP Connectors
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP-Server from your Database optimized for LLMs and AI-Agents. Supports PostgreSQL, MySQL, ClickHouse, Snowflake, MSSQL, BigQuery, Oracle Database, SQLite, ElasticSearch, DuckDB550Apache 2.0

Altinity MCPofficial
FlicenseNot gradedqualityBmaintenanceProduction-ready MCP server designed to empower AI agents and LLMs to interact seamlessly with ClickHouse. It exposes your ClickHouse database as a set of standardized tools and resources that adhere to the MCP protocol, making it easy for agents built on OpenAI, Claude, or other platforms to query, explore, and analyse your data.39-- AlicenseAqualityBmaintenanceOne config, one CLI that turns your databases (Postgres, MySQL, SQLite, MongoDB) into MCP servers for Claude, GPT, Cursor, and any MCP-compatible agent.31MIT
- AlicenseAqualityAmaintenanceA dead-simple, self-hosted MCP server for querying your databases with AI agents.423502 PyPI2MIT