AI agent for ClickHouse database analysis via MCP
Wellknown found it in public sources; nobody has proven control of it yet. Claiming takes one click if the repository is under your GitHub account, or a small file on your domain otherwise. Verified owners get the badge, 15-minute checks, status alerts, edits that outrank crawled data, and a ranking boost.
Agents can do it too: POST https://wellknown.network/api/v1/claims with {"agent":"clickhouse-mcp-agent","method":"well_known_file"} — machine-readable steps at claim.json, guide at /docs/claim.
Everything here was measured by our prober or read from a registry. Nothing is self-reported.
Attributed to the source that supplied each field. Treated as claims, not facts.
# ClickHouse MCP Agent [](https://pypi.org/project/clickhouse-mcp-agent/) [](https://pypi.org/project/pydantic-ai-slim/) [](https://pypi.org/project/mcp-clickhouse/) AI agent for ClickHouse database analysis via MCP (Model Context Protocol). A single MCP server (`mcp-clickhouse`) driven by a single agent instance. You can scope what the agent discovers per call with allow-lists (`allowed_tables`, `allowed_databases`). See [Security](#security) for what they do and do not restrict. ## Features - Query ClickHouse databases using natural language with AI models - Structured output: `analysis`, `confidence`, `sql_used` - Easy connection management (predefined or custom) - Conversational context with message-history pruning/summarization - No CLI or external .env required — configure at runtime - Per-call discovery scoping via allow-lists (`allowed_tables`, `allowed_databases`) - Read-only queries by default (enforced by `mcp-clickhouse`) - Streamable results via `run_stream()` - Persistent MCP server mode via `async with ClickHouseAgent()` - Parallel queries via `run_batch()` - Lifecycle reset via `reset()` - Query result cache via `enable_cache=True` - Typed exception hierarchy for reliable error handling - Optional `structlog` integration (`pip install ".[logging]"`) ### Supported Providers | Provider | Key env var | Notes | |---|---|---| | Google Gemini | `GOOGLE_API_KEY` | Default | | OpenAI | `OPENAI_API_KEY` | | | Anthropic | `ANTHROPIC_API_KEY` | | | Grok (xAI) | `XAI_API_KEY` | Model prefix `xai:` (e.g. `xai:grok-4`) | | Groq | `GROQ_API_KEY` | Fast open models (e.g. `groq:llama-3.3-70b-versatile`), free tier | | Mistral | `MISTRAL_API_KEY` | | | Cohere | `CO_API_KEY` | | ## Local Development (Docker) The fastest way to get started — no cloud …
Mapped onto the structured taxonomy from declared text and observed tool names. Confidence shown for derived entries.
Every source is kept verbatim. Field changes are logged as events.