# ClickHouse MCP — Read-Only Defaults + Drop Protection

> ClickHouse MCP connects MCP clients to ClickHouse or embedded chDB with read-only defaults, optional writes, and double opt-in for DROP/TRUNCATE safety.

## Install

Merge the JSON below into your `.mcp.json`:

## Quick Use

1. Install:
   ```bash
   python3 -m pip install mcp-clickhouse
   ```
2. Configure Claude Desktop (uv-based example):
   ```json
   {
     "mcpServers": {
       "mcp-clickhouse": {
         "command": "uv",
         "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
         "env": {
           "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
           "CLICKHOUSE_PORT": "8443",
           "CLICKHOUSE_USER": "demo",
           "CLICKHOUSE_PASSWORD": "",
           "CLICKHOUSE_SECURE": "true",
           "CLICKHOUSE_VERIFY": "true"
         }
       }
     }
   }
   ```
3. Verify: run a `SELECT` and confirm mutations are blocked unless you explicitly enable writes.

## Intro

ClickHouse MCP connects MCP clients to ClickHouse or embedded chDB with read-only defaults, optional writes, and double opt-in for DROP/TRUNCATE safety.

- **Best for:** teams that want ClickHouse analytics access for agents but need strict safety controls for mutations and drops
- **Works with:** ClickHouse or chDB, Python + uv/pip, MCP clients (Claude Desktop, Cursor) via stdio/HTTP
- **Setup time:** 10-30 minutes

## Practical Notes

- Quant: keep `CLICKHOUSE_ALLOW_WRITE_ACCESS` off by default; enable it only for controlled workflows (migrations, backfills).
- Quant: destructive ops require a second flag (`CLICKHOUSE_ALLOW_DROP=true`)—use that as a policy gate for production safety.

## Why it matters

ClickHouse MCP is valuable when you want natural-language analytics over ClickHouse, but your ops posture demands strong “no accidental DROP” guardrails.

- Documents both ClickHouse and embedded chDB modes, covering remote analytics and local embedded use cases.
- Read-only is the default, with explicit environment flags for escalating capabilities.
- Provides authentication guidance (token/OIDC) for HTTP/SSE transports, which matters for shared deployments.

## Rollout pattern

- Start with the ClickHouse SQL playground credentials or a staging cluster to validate connectivity and result formats.
- Keep writes disabled; create a second server instance for admin tasks if you truly need mutations.
- Enable auth before exposing HTTP/SSE to any shared network and rotate tokens regularly.

## Watchouts

Even with write flags off, leaking sensitive query results into an LLM is still a risk. Apply query limits, masking, and least-privilege credentials.

### FAQ

**Q: Can it work without ClickHouse (local only)?**
A: Yes. The README describes a chDB mode that runs an embedded ClickHouse engine.

**Q: How do I enable writes safely?**
A: Set `CLICKHOUSE_ALLOW_WRITE_ACCESS=true`, and keep `CLICKHOUSE_ALLOW_DROP` off unless you explicitly need destructive operations.

**Q: What should I test first?**
A: Run one `SELECT` against a known table and verify the server refuses mutation queries in default mode.

## Source & Thanks

> Source: https://github.com/ClickHouse/mcp-clickhouse
> License: Apache-2.0
> GitHub stars: 777 · forks: 180

---

<!-- ZH -->

## 快速使用

1. 安装：
   ```bash
   python3 -m pip install mcp-clickhouse
   ```
2. 配置 Claude Desktop（uv 示例）：
   ```json
   {
     "mcpServers": {
       "mcp-clickhouse": {
         "command": "uv",
         "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
         "env": {
           "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
           "CLICKHOUSE_PORT": "8443",
           "CLICKHOUSE_USER": "demo",
           "CLICKHOUSE_PASSWORD": "",
           "CLICKHOUSE_SECURE": "true",
           "CLICKHOUSE_VERIFY": "true"
         }
       }
     }
   }
   ```
3. 验证：先跑 `SELECT`，并确认未显式开启写权限时，变更类语句会被阻止。

## 简介

ClickHouse MCP 为 MCP 客户端提供 ClickHouse/chDB 访问能力，默认只读执行查询；可选开启写入，并通过额外开关保护 DROP/TRUNCATE 等破坏性操作，适合让 Agent 安全做分析与排障。

- **适合谁：** 希望让 Agent 访问 ClickHouse 做分析，但对写入/误删有严格安全要求的团队
- **可搭配：** ClickHouse 或 chDB、Python + uv/pip、支持 MCP 的客户端（Claude Desktop / Cursor），可 stdio/HTTP
- **准备时间：** 10-30 分钟

## 实战建议

- 量化信息：默认关闭 `CLICKHOUSE_ALLOW_WRITE_ACCESS`；仅在迁移/回填等受控流程里开启。
- 量化信息：DROP/TRUNCATE 需要第二个开关（`CLICKHOUSE_ALLOW_DROP=true`）；把它当作生产安全的政策闸门。

## 为什么值得收录

当你想让 Agent 以自然语言跑 ClickHouse 分析，但运维侧又必须严控“误删/误写”时，这种“双重开关”的 MCP server 很实用。

- 同时覆盖 ClickHouse 与嵌入式 chDB 两种模式，适配远程分析与本地嵌入场景。
- 默认只读，并用显式环境变量分级开放能力。
- 对 HTTP/SSE 的鉴权（token/OIDC）给出指导，适合共享部署。

## 落地路径

- 先用 SQL Playground 或 staging 集群验证连通性与结果格式。
- 写权限保持关闭；若确实需要变更操作，建议单独部署第二个实例。
- HTTP/SSE 暴露到共享网络前先把鉴权打开，并定期轮换 token。

## 注意事项

即便默认只读，敏感查询结果进入 LLM 上下文仍然有风险。建议加查询限制、脱敏与最小权限凭证。

### FAQ

**没有 ClickHouse 也能用吗？**
答：可以。README 提到 chDB 模式，可在本地用嵌入式 ClickHouse 引擎。

**如何安全开启写入？**
答：设置 `CLICKHOUSE_ALLOW_WRITE_ACCESS=true`；除非明确需要，否则保持 `CLICKHOUSE_ALLOW_DROP` 关闭。

**先测什么最稳？**
答：先跑一条 `SELECT`，确认默认模式会拒绝变更类语句。

## 来源与感谢

> Source: https://github.com/ClickHouse/mcp-clickhouse
> License: Apache-2.0
> GitHub stars: 777 · forks: 180


---
Source: https://tokrepo.com/en/workflows/clickhouse-mcp-read-only-defaults-drop-protection
Author: MCP Hub