ClickHouse MCP

ClickHouse's official MCP server: agents can list databases and tables and run SQL queries against your ClickHouse cluster (read-only by default).

🗄️ Databases & vector stores889Updated 2026-10-15By ClickHouseLicense: Apache-2.0Auth: Not checked yetGitHub ↗

Found viaWebOfficial MCP Registry: io.github.ClickHouse/mcp-clickhouse GitHubGitHub: ClickHouse/mcp-clickhouse (★ 889 on 2026-10-18) MakerClickHouse docs: MCP integrations

Test results

Last passed 2026-10-23

Claude CodePassed2026-10-23 · install, connect, tools, agent taskTested with Claude Code 2.1.296 · mcp-clickhouse 0.7.0 · connected in 3.3s

CursorPassed2026-10-23 · install, connect, tools, agent taskTested with Cursor CLI 2026.10.22-27dcf5f · mcp-clickhouse 0.7.0 · connected in 1.8s

Claude DesktopNot tested yet—

ChatGPT (Codex)Passed2026-10-23 · install, connect, tools, agent taskTested with Codex CLI 0.162.0-alpha.17.2 · mcp-clickhouse 0.7.0 · connect time not recorded

Server package tested: mcp-clickhouse 0.7.0 (uv, Python 3.12.15; resolved 2026-10-23)

Direct and key dependencies as resolved: anyio 4.15.1 · cachetools 7.2.4 · clickhouse-connect 1.11.0 · fastmcp 4.0.11 · mcp 2.3.0 · pydantic 2.14.1 · pydantic-settings 2.16.1 · pydantic_core 2.50.1 · python-dotenv 1.2.4 · simplejson 4.2.0 · sse-starlette 3.5.0 · starlette 1.9.0 · truststore 0.10.5 · typing_extensions 4.16.0 · uvicorn 0.54.0

All 82 resolved dependencies

aiofile==3.12.3
annotated-types==0.8.0
anyio==4.15.1
attrs==26.1.0
Authlib==1.9.1
backports.zstd==1.8.0
beartype==0.23.1
cachetools==7.2.4
caio==0.12.10
certifi==2026.10.23
cffi==2.1.1
chdb==4.4.0
chdb-core==26.9.0
click==8.5.0
clickhouse-connect==1.11.0
cryptography==50.0.2
cyclopts==5.3.0
dnspython==2.9.0
docstring_parser==0.18.0
email-validator==2.3.0
exceptiongroup==1.3.1
fastmcp==4.0.11
fastmcp-slim==4.0.11
griffelib==2.4.1
h11==0.16.0
httpcore2==2.16.0
httpx2==2.16.0
idna==3.20
jaraco.classes==3.4.0
jaraco.context==6.1.2
jaraco.functools==4.6.0
jeepney==0.9.0
joserfc==1.7.7
jsonref==1.1.0
jsonschema==4.26.0
jsonschema-path==0.5.0
jsonschema-specifications==2025.9.1
keyring==25.7.0
lz4==4.4.5
markdown-it-py==4.2.0
mcp==2.3.0
mcp-types==2.3.0
mdurl==0.1.2
more-itertools==11.2.1
numpy==2.5.4
openapi-pydantic==0.6.0
opentelemetry-api==1.45.1
packaging==26.3
pandas==3.1.0
pathable==0.6.0
platformdirs==4.13.5
py-key-value-aio==0.4.6
pyarrow==26.0.0
pycparser==3.12
pydantic==2.14.1
pydantic-settings==2.16.1
pydantic_core==2.50.1
Pygments==2.21.0
PyJWT==2.15.1
pyperclip==1.11.0
python-dateutil==3.0.0
python-dotenv==1.2.4
python-multipart==0.0.32
PyYAML==6.0.3
referencing==0.37.0
rich==15.0.0
rich-rst==2.2.0
rpds-py==2026.9.1
SecretStorage==3.5.0
simplejson==4.2.0
six==1.17.0
sse-starlette==3.5.0
starlette==1.9.0
truststore==0.10.5
typing-inspection==0.4.4
typing_extensions==4.16.0
tzdata==2026.5
uncalled-for==0.4.1
urllib3==2.8.0
uvicorn==0.54.0
watchfiles==1.3.0
websockets==17.3

Captured with: uvx --from mcp-clickhouse[chdb] python (importlib.metadata in the same uvx env; equivalent to uv pip freeze).

Full result per app: Does it work with Claude Code? · Does it work with Cursor? · Does it work with ChatGPT (Codex)?

Protocol: starts, 1 tools listed · 2026-10-23 · connected in 7.6s

🧪 Test-box note: Embedded chDB mode (no ClickHouse server, no credentials); a CSV fixture in the harness sandbox is queried directly. The ClickHouse-cluster tools were not tested.

Real test

Passed

One run from our records. When two runs share a date, we show a failure if there is one.

Client

ChatGPT (Codex) · Codex CLI 0.162.0-alpha.17.2

Date

Oct 23, 2026

The task we gave

Using only the clickhouse-mcp MCP tools, query the CSV file /workspace/timmy/harness/sandbox/chdb/orders.csv (columns id, item, code) and reply with the code of the row whose item is 'lamp'.

What it promised

details not recorded for this run

What happened

Tool calls:

clickhouse-mcp:run_chdb_select_query

Tool result

{"content": [{"type": "text", "text": "[{\"code\": \"TP-005780\"}]"}], "_meta": {"fastmcp": {"wrap_result": true}}, "structured_content": {"result": "[{\"code\": \"TP-005780\"}]"}}

Agent reply

TP-005780

Verdict

Passed

Install

claude mcp add clickhouse-mcp -e CHDB_ENABLED=true -e CLICKHOUSE_ENABLED=false -- uvx --from mcp-clickhouse[chdb] mcp-clickhouse

Run in your terminal. This exact command is what our harness runs in Claude Code; see the results above.

{
  "mcpServers": {
    "clickhouse-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-clickhouse[chdb]",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false"
      }
    }
  }
}

Save as .cursor/mcp.json. This exact config is what our harness runs in Cursor; see the results above.

{
  "mcpServers": {
    "clickhouse-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-clickhouse[chdb]",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false"
      }
    }
  }
}

Add to claude_desktop_config.json and restart Claude Desktop. Tested on the Linux beta; see the results above.

[mcp_servers.clickhouse-mcp]
command = "uvx"
args = ["--from", "mcp-clickhouse[chdb]", "mcp-clickhouse"]
env = { CHDB_ENABLED = "true", CLICKHOUSE_ENABLED = "false" }

Add to ~/.codex/config.toml (shared by the ChatGPT (Codex) CLI and the ChatGPT desktop app; Codex runs inside the ChatGPT desktop app). Tested with the ChatGPT (Codex) CLI bundled in the ChatGPT desktop app; see the results above.

Not connecting? Troubleshooting: Claude Code · Cursor · Claude Desktop · ChatGPT (Codex)

Test history

Date	Check	Result	Versions tested
2026-10-23	Protocol (direct stdio)	Protocol: starts, 1 tools listed	mcp-clickhouse 0.7.0 · server reported v0.7.0
2026-10-23	Claude Code	Passed install, connect, tools, agent task	Claude Code 2.1.296 · mcp-clickhouse 0.7.0
2026-10-23	Cursor	Passed install, connect, tools, agent task	Cursor CLI 2026.10.22-27dcf5f · mcp-clickhouse 0.7.0
2026-10-23	ChatGPT (Codex)	Passed install, connect, tools, agent task	Codex CLI 0.162.0-alpha.17.2 · mcp-clickhouse 0.7.0

Tools seen by our harness (1)

run_chdb_select_query