ClickHouse/mcp-clickhouse

What it solves

This project provides a Model Context Protocol (MCP) server that allows AI agents (like Claude Desktop) to interact directly with ClickHouse databases. It bridges the gap between LLMs and high-performance analytical databases, enabling agents to query data, list tables, and explore database schemas without manual data exports.

How it works

The server implements the MCP standard to expose ClickHouse functionality as a set of tools that an LLM can call. It supports two primary engines:

• ClickHouse Cluster: Connects to a remote ClickHouse instance via HTTP to execute SQL queries and manage database metadata.
• chDB: An embedded ClickHouse engine that allows querying data directly from files or URLs without requiring a full database installation.

It includes a two-tier security system to prevent accidental data loss, requiring specific environment flags (CLICKHOUSE_ALLOW_WRITE_ACCESS and CLICKHOUSE_ALLOW_DROP) to enable mutations or destructive operations.

Who it’s for

• Data Analysts and Engineers: Who want to use AI agents to perform exploratory data analysis on ClickHouse datasets.
• AI Application Developers: Building agents that need real-time access to analytical data stored in ClickHouse.
• Database Administrators: Who need a secure, read-only interface for LLMs to interact with their data.

Highlights

• Dual Engine Support: Works with both full ClickHouse clusters and the embedded chDB engine.
• Safety Guards: Default read-only mode with explicit opt-in for write and destructive operations (DROP, TRUNCATE, etc.).
• Flexible Authentication: Supports static bearer tokens and OAuth/OIDC (via FastMCP) for secure HTTP/SSE transports.
• Extensible Architecture: Includes a middleware system to intercept tool calls, log requests, or dynamically override client configurations.