mcp-clickhouse
Connect ClickHouse to your AI assistants.
The ClickHouse MCP server connects ClickHouse databases and the chDB embedded engine to AI assistants via the Model Context Protocol. It enables AI agents to execute SQL queries, inspect database schemas, list tables and databases, and analyze query performance through tools like run_query, list_databases, and list_tables. The server supports both remote ClickHouse clusters and local chDB instances, with configurable read-only or write-enabled modes, comprehensive authentication options including OAuth/OIDC, and built-in safety guards against destructive operations.
Key Features
Use Cases
- 01Enable AI assistants to query and analyze data in production ClickHouse clusters
- 02Allow Claude Desktop to explore database schemas and generate SQL queries interactively
- 03Validate expensive queries with EXPLAIN ESTIMATE before execution to avoid resource exhaustion
- 04Run embedded analytics on local files and URLs using chDB without setting up a database server
- 05Provide read-only database access to AI agents for safe exploratory data analysis
- 06Deploy authenticated MCP endpoints behind Kubernetes ingress with OAuth/OIDC for enterprise AI workflows
Related MCP Servers
View moremarkitdown
Python tool for converting files and office documents to Markdown.
firecrawl
The context API to search, scrape, and interact with the web at scale. 🔥
prompts.chat
f.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete privacy.
langflow
Langflow is a powerful tool for building and deploying AI-powered agents and workflows.
mcp-clickhouse — FAQ
What is the ClickHouse MCP server?+
It's an MCP server that connects ClickHouse databases and the chDB embedded engine to AI assistants, allowing them to execute SQL queries, inspect schemas, and analyze data through the Model Context Protocol.
How do I install the ClickHouse MCP server in Claude Desktop?+
Install it via uv by adding a configuration entry to claude_desktop_config.json with the command 'uv run --with mcp-clickhouse --python 3.12 mcp-clickhouse' and environment variables for your ClickHouse connection. Alternatively, install globally with 'pip install mcp-clickhouse' and use 'python3 -m mcp_clickhouse.main' as the command.
Which AI clients work with this MCP server?+
It works with any MCP-compatible client including Claude Desktop, and supports both stdio transport (default for desktop clients) and HTTP/SSE transports for remote access and tools like MCP Inspector.
Do I need API keys or credentials to use this server?+
Yes, you need ClickHouse connection credentials (CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD). For HTTP/SSE transports, you also need authentication configured via bearer token, OAuth/OIDC provider, or explicitly disabled for local development only.
Is the ClickHouse MCP server free to use?+
Yes, the MCP server itself is free and open source. However, you need access to a ClickHouse database (self-hosted, cloud, or the free SQL Playground) or can use the embedded chDB engine.
Does it support write operations and how are destructive queries protected?+
Write operations require CLICKHOUSE_ALLOW_WRITE_ACCESS=true, which defaults to read-only mode. Destructive operations (DROP, TRUNCATE, DELETE, UPDATE) additionally require CLICKHOUSE_ALLOW_DROP=true as a two-tier safety system, though the real security boundary is ClickHouse user grants.
How do I install mcp-clickhouse?+
Open the source repository on GitHub and follow its README. mcp-clickhouse is a mcp server — MCP Agents Market links you directly to the official repo.
Is mcp-clickhouse free?+
mcp-clickhouse is an open-source project hosted on GitHub. Check the repository for its license and any usage requirements.